Organisation change for the Handbook
Nik Clayton
People seem to be a bit more active on this list recently, so I'm reposting
something from November last year. Now that the DocBook conversion is
done I'm looking at this in more detail, and would appreciate comments.
Sean Kelly, Jordan, Eivind, and Sue Blake[1] will recognise some of this.
Also, this is long, sorry about that.
N
[1] Do you know you've arrived in the FreeBSD project when people just
refer to you by your first name?
=========================================================================
Handbook Reorganisation
The basic idea is simple. The Handbook has grown fairly organically, and
can be reorganised. This reorganisation should reflect how people use the
Handbook, and allow for currently missing content to be slotted in more
easily.
This should also make it easier for projects, such as "FreeBSD Installation
Guide" or the "Programmers Documentation Project" to slip right in to this
framework. If necessary, people can maintain their own books out of the
main FreeBSD doc tree, while still maintaining the FreeBSD look and feel and
integration with the rest of the docs (if they want to, of course).
The Handbook's target audience needs to be understood. The Handbook should
be catering for the spectrum of people who, at one end, have never heard of
Unix or FreeBSD before through to those people who are very familiar with
FreeBSD, but who need a useful reference, or want to know as much as
possible about a topic they haven't yet covered (for example, printing).
This is likely to yield quite a schizophrenic document unless tackled
carefully.
The gist of my proposal is to split the Handbook up in to a number of
smaller books, containing between 70-150 'pages'. These would then truly be
*hand*books. Each book should tackle one topic, and not repeat information
from one of the other books. For example, if a book's topic requires that
the reader reconfigure their kernel (for example, Firewalls), they should be
directed to the appropriate part of the "Configuring FreeBSD" book, instead
of repeating that information there.
A seasoned system administrator will be able to go to whichever book tackles
the task they are trying to complete, without getting bogged down in
extraneous detail. Someone new to FreeBSD will be told "Read these 'x'
books first (which cover installation and configuration) and then go and
read whichever of the other books talk about what you are interested in" to
bring them up to speed.
Note that it should be assumed that the reader has at least some OS
experience. I think it is biting off more than we can chew if we assume we
need to teach OS basics as well (although that could be a topic for another
book in the series, which would give the user enough knowledge to then move
on to some of the others).
Each book conforms to a similar organisation. They begin with an overview
explaining what will be tackled by that book, and what the user will be
able to do when they have completed the book. Any prerequisite knowledge
that the user must have is also outlined here.
The rest of the book then works through whatever that section is talking
about, until the user has done whatever it is they want to do. In general,
if the section requires hardware ("Printing", "Modems", "Ethernet". . .)
then the installation and configuration of that hardware is covered first --
this should cover the physical installation of the hardware ("Plug in your
ethernet card in accordance with the manufacturers instructions") and the
configuration necessary to get FreeBSD to recognise the hardware ("Add the
line "device ..." to your kernel config file and rebuild your kernel. If you
don't know what this means then please read the "Configuring your kernel"
book"). Then the software is covered. In some cases this might include
several different applications. Finally, a "Further reading" section can
cover books, magazines, web sites, and other books in the series.
------------------------------------------------------------------------
Here's how I see the new books shaping up. Note that a lot of the
content doesn't exist yet. My comments are bracketed by '[' and ']'
after each book.
Note that the ordering of books here is *not* implying an order in which
people should be expected to read them.
Book 0: Read This First
Conventions in this documentation (foreward? preface?)
Introduction
Differences from. . .
- DOS
- Linux
- Solaris
- SunOS
- BSDi
- NetBSD
- OpenBSD
Obtaining FreeBSD
Installing FreeBSD
- PC Hardware Compatibility
Unix Basics
[ This is the one that everyone should read first. There's no reason why
the "Installing FreeBSD" and "Unix Basics" chapters couldn't be
separate books in their own right. ]
Book 1: Configuring FreeBSD
Overview
- What you can configure
Making configuration changes
- At boot time (start up)
- At run time
- In the kernel
Further reading
[ If you want to configure FreeBSD then read this. /etc/rc.conf, rc.local,
/usr/local/etc/rc.d/*, how to configure a new kernel, sysctl and other
tunables. This talks about the process, rather than how you would configure
any particular option. Another book might say "Add the foo device to the
kernel", this book explains how to do that. ]
Book 2: Installing Applications
Using the ports collection to install applications
Installing applications by hand
[ Self evident ]
Book 3: Monitoring and limiting users
Overview
login.conf
Disk quotas
Process accounting
Further reading
[ Self evident ]
Book 4: Security
Overview
S/Key
Kerberos
SSH
Further reading
- Firewalls
[ Self evident. Content shamelessly taken from the security section in
the existing Handbook ]
Book 5: The text console
Overview
Syscons
- Virtual terminals
- Fonts
- Using the mouse with syscons
PCVT
Further reading
[ Doesn't currently exist, probably should do. ]
Book 6: Printing
Overview
Hardware setup
The LPD Spooler
...
The LPNG Spooler
...
Printing to printers on other computers
- Windows NT
- Linux
- Macintosh
Further reading
[ Shamelessly taken from existing Handbook ]
Book 7: Using modems and null modems (serial connections)
Overview
Before using a modem with FreeBSD
Using a modem/serial line to talk to remote hosts
Further reading
[ Based on existing content in the Handbook ]
Book 8: TCP/IP Networking (the Internet)
Overview
- IP addresses, netmasks
- Gateways and routing
TCP/IP
- PPP
- SLIP
- Ethernet
DNS
NIS
Security (firewalls)
Further reading
[ A reordering, and an addition to, existing content ]
Book 9: Electronic Mail Servers
Overview
SMTP
- Sendmail
- Qmail
POP
IMAP
Further reading
[ Doesn't currently exist. Would explain the basics of SMTP, what an
MTA does, and how to use the popular ones ]
Book 10: Electronic Mail Clients
Overview
FreeBSD
- Mutt
- Elm
- XFmail
- PINE
Windows
- Eudora
Macintosh
- Eudora
Further reading
[ Doesn't currently exist. This is where the Mutt/Pine/rmail fanatics
get to fight it out with one another. Include chapters explaining how
to configure common MUAs on other platforms to read their mail from
FreeBSD ]
Book 11: File sharing
Overview
NFS
SMB
Coda
Appletalk
Further reading
[ Self evident ]
Book 12: Time/date synchronization
Overview
- NTP
Being a time server
Synchronising from a time server
Synchronising NT to FreeBSD
Synchronising MacOS to FreeBSD
Further reading
[ Self evident ]
Book 13: X11
Overview
XFree86 / XiG
Window Managers
Useful X applications
Further reading
[ Self evident ]
Book 14: Applications
Overview
Mathematica
Doom
Quake
Further reading
[ For those applications that crop up a lot in -questions, or where someone is
motivated enough to write something. Could probably include StarOffice and
Word Perfect in this list as well. ]
Book 15: Staying up to date with FreeBSD
Overview
- Choosing -current?
- Choosing -stable?
Getting the source
- FTP
- CVSup
- CTM
Updating your system ('make world')
Further reading
[ Mostly based on current Handbook content ]
Book 16: Emulation
Overview
Linux
SCO
DOS
- dosemu
- pcemu
Further reading
[ A reorganisation and addition to current content ]
Book 17: Localisation
Overview
Russian
German
Further reading
[ From the existing Handbook ]
Book 18: Contributing to FreeBSD
Overview
- What is needed?
Bug reports
Documentation
Code
- Source tree guidelines and policies
- Changes to existing code
- New code
- FreeBSD Internals
- Kernel debugging
Application ports
Hardware/architecture ports
Money, hardware, or Internet access
The committers guide
[ From the existing Handbook ]
Appendices
Bibliography
Resources on the Internet
FreeBSD Project Staff
Contributors
- Donors Gallery
- Derived Software Contributors
- Additional FreeBSD Contributors
- 386BSD Patch Kit Contributors
PGP Keys
[ This will, I think, be split up. Most of the new books will need their own
biblios, so that section will probably disappear, as will the "Resources on
the Internet" section. PGP Keys might move to "Security" as well. ]
Thanks for reading this far. There are two more books at the back of my mind
that aren't on that list yet.
The first is the "Doc. Proj. primer". If you take a look at
http://www.freebsd.org/~nik/primer/, that's pretty much what I'm expecting one
of these books to look like[1] (in terms of amount of content, level it's aimed
at, and so on).
The second is the Committers Guide. This might be part of the "Contributing
to FreeBSD" book, or it might be one on its own. I'm not sure yet.
Comments welcomed,
N
[1] Yes, I know I've got to commit the primer to the main tree. After not
staring at it for a couple of months I'm rewriting a few bits that are
either confusing or wrong prior to committing. Expect it by the end of
this week.
--
Bagel: The carbohydrate with the hole
To Unsubscribe: send mail to majo...@FreeBSD.org
with "unsubscribe freebsd-doc" in the body of the message
Dan Langille
> People seem to be a bit more active on this list recently, so I'm
> reposting something from November last year. Now that the DocBook
> conversion is done I'm looking at this in more detail, and would
> appreciate comments.
I missed the original post as I was on hoilday and unsubscribed. I'm
sorry I missed it back then.
> The Handbook's target audience needs to be understood. The Handbook
> should be catering for the spectrum of people who, at one end, have
> never heard of Unix or FreeBSD before through to those people who are
> very familiar with FreeBSD, but who need a useful reference, or want to
> know as much as possible about a topic they haven't yet covered (for
> example, printing).
This is great! And what Darren was talking about.
> Note that it should be assumed that the reader has at least some OS
> experience. I think it is biting off more than we can chew if we assume
> we need to teach OS basics as well (although that could be a topic for
> another book in the series, which would give the user enough knowledge
> to then move on to some of the others).
That doesn't mean we can't have a newbie section that says here's the
editor, here's the basic commands, etc. One page intro. We are not here
to educate computer novices. Merely FreeBSD novices.
> Here's how I see the new books shaping up. Note that a lot of the
> content doesn't exist yet. My comments are bracketed by '[' and ']'
> after each book.
What I like about it is that each section is *not* self contained. That
allows the author of one section to refer to existing work (e.g. Add the
IPFILTER option to your kernel). It makes the writing much easier. Not
to mention the reading.
--
Dan Langille
The FreeBSD Diary
http://www.FreeBSDDiary.com/freebsd
Bill Fumerola
> > [1] Do you know you've arrived in the FreeBSD project when people just
> > refer to you by your first name?
>
> No, you just know that your first name is still unique enough to make
> that even possible. :-)
My name is ambiguous even with a first name and last initial. Sigh.
- bill fumerola - bi...@chc-chimes.com - BF1560 - computer horizons corp -
- ph:(800) 252-2421 - bfum...@computerhorizons.com - bi...@FreeBSD.org -
Donald Wilde
> My name is ambiguous even with a first name and last initial. Sigh.
>
associate you with those _other_ Bill's that are giving the name a very
_bad_ reputation... ;-)
--
Don Wilde "Bringing the Internet to everyone!"
Wilde Media
1380 Rio Rancho Blvd. SE #117 voice: 505-771-0709
Rio Rancho, New Mexico 87124 e-mail: dwi...@thuntek.net
Bill Fumerola
> Bill Fumerola wrote:
> > My name is ambiguous even with a first name and last initial. Sigh.
> >
> Yah, Bill, better always use your last initial or somebody might
> associate you with those _other_ Bill's that are giving the name a very
> _bad_ reputation... ;-)
Bill F{umerola,enner} = {billf,fenner}@FreeBSD.org
I have to go full name.
- bill fumerola - bi...@chc-chimes.com - BF1560 - computer horizons corp -
- ph:(800) 252-2421 - bfum...@computerhorizons.com - bi...@FreeBSD.org -
To Unsubscribe: send mail to majo...@FreeBSD.org
Sean Kelly
reorgani[sz]ation, let's give it another go.
I just want to reiterate some of my views from last time, change some,
and add some new ones:
> The basic idea is simple. The Handbook has grown fairly organically, and
> can be reorganised.
Merely because we can do a thing does not mean we must do that thing!
(Bonus points to whoever recognizes the line and the movie.)
But, in this case, the organic development was good in order to pound
out a handbook. Now that we've got a sizeable amount of material, I
agree that it's time to put it into a coherent structure.
> If necessary, people can maintain their own books out of the
> main FreeBSD doc tree, while still maintaining the FreeBSD look and feel and
> integration with the rest of the docs (if they want to, of course).
They better ... or else! :-)
> The Handbook's target audience needs to be understood. The Handbook should
> be catering for the spectrum of people who, at one end, have never heard of
> Unix or FreeBSD before through to those people who are very familiar with
> FreeBSD, but who need a useful reference, or want to know as much as
> possible about a topic they haven't yet covered (for example, printing).
Writing and/or reorganizing for an audience that exists at both ends of
the spectrum is going to be a challenge. Knuth failed to do this
effectively at all in his "TeXBook." We know one approach to avoid, at
least. But is there a decent approach?
> This is likely to yield quite a schizophrenic document unless tackled
> carefully.
Uh, I basically just said that. :-)
> The gist of my proposal is to split the Handbook up in to a number of
> smaller books, containing between 70-150 'pages'. These would then truly be
> *hand*books. Each book should tackle one topic, and not repeat information
> from one of the other books. For example, if a book's topic requires that
> the reader reconfigure their kernel (for example, Firewalls), they should be
> directed to the appropriate part of the "Configuring FreeBSD" book, instead
> of repeating that information there.
I mostly agree. In particular, kernel configuration is one of out
better chapters in the current handbook. Yet some amount of kernel
configuration appears in nearly all the other chapters: in networking on
setting up the kernel with an Ethernet controller; in printing on
setting up the kernel for parallel ports; etc.
I think the terminology is just tripping me up, here: are these really
separate books? Will these be toplevel Docbook "book" elements? I'm
wondering if there exists enough material in each book to warrant a
book, and thence a collection for all of our documentation.
> [ new organization ]
Okay, I'm warming up to the idea now. In particular, "Unix Basics"
ought to be its own book. A Unix expert doesn't need all that extra
material if s/he just wants to know how to install FreeBSD.
Some of the material for "the text console" does exist "off-site." I
remember someone writing a tutorial on setting up fonts, mouse, etc.
Does anyone have the URL?
Finally, don't forget that we'll need a separate book that's a compiled
index to the whole collection.
Best,
--Sean
Duncan Barclay
On 05-Apr-99 Nik Clayton wrote:
> Hi folks,
>
> People seem to be a bit more active on this list recently, so I'm reposting
> something from November last year. Now that the DocBook conversion is
> done I'm looking at this in more detail, and would appreciate comments.
>
> Sean Kelly, Jordan, Eivind, and Sue Blake[1] will recognise some of this.
>
> Also, this is long, sorry about that.
>
> N
[books removed...]
Minor nits - no exim in the MTAs and Usenet completely missing (shameless plug -
inn primer/setup stuff is available from http://www.ragnet.demon.co.uk/mynews/
and I'm happy to work on it so that it fits your new handbook framework.)
Duncan
___
_____________________________________________________________________
Duncan Barclay | God smiles upon the little children,
dm...@ragnet.demon.co.uk | the alcoholics, and the permanently stoned.
________________________________________________________________________
Satoshi - the Wraith - Asami
* My name is ambiguous even with a first name and last initial. Sigh.
That's what you get by having such a generic (and evil) first name. :>
-PW
P.S. Have you tried "xbill"?
Nik Clayton
> Minor nits - no exim in the MTAs and Usenet completely missing
> (shameless plug - inn primer/setup stuff is available from
> http://www.ragnet.demon.co.uk/mynews/ and I'm happy to work on it so
> that it fits your new handbook framework.)
I'll have the PPMail guys complaining next. . .
Yeah. One of the benefits of this approach is that it makes it easier
to slot new material in, and at the same time simpler to hand off
chunks to volunteers and say "Here's a complete framework, all it needs
is content".
N
Nik Clayton
> On Tue, 6 Apr 1999, Donald Wilde wrote:
> > Bill Fumerola wrote:
> > >
> > associate you with those _other_ Bill's that are giving the name a very
> > _bad_ reputation... ;-)
>
> Bill F{umerola,enner} = {billf,fenner}@FreeBSD.org
>
> I have to go full name.
OK, when you guys have *quite* finished :-)
Anyone got any comments about the other 356 lines in my mail :-) ?
N
. . . <sigh> I don't know. You spend hours putting something together,
and everyone latches on to the 2 line throwaway comment. . .
Nik Clayton
[ snippage; we're in agreement ]
> > The gist of my proposal is to split the Handbook up in to a number of
> > smaller books, containing between 70-150 'pages'. These would then truly be
> > *hand*books. Each book should tackle one topic, and not repeat information
> > from one of the other books. For example, if a book's topic requires that
> > the reader reconfigure their kernel (for example, Firewalls), they should be
> > directed to the appropriate part of the "Configuring FreeBSD" book, instead
> > of repeating that information there.
>
> I mostly agree. In particular, kernel configuration is one of out
> better chapters in the current handbook. Yet some amount of kernel
> configuration appears in nearly all the other chapters: in networking on
> setting up the kernel with an Ethernet controller; in printing on
> setting up the kernel for parallel ports; etc.
Yep. One of the things each book will need is a "_topic_ for the
impatient". This is just bullet points that provide the minimal
information for those that know what they're doing, and don't need
handholding.
For Kernel Configuration this would be something like;
* Make sure you've installed the kernel sources.
* Copy /sys/i386/conf/GENERIC /sys/i386/conf/KERNELNAME, where
KERNELNAME is the name you want for your new kernel.
* Read the comments in GENERIC and LINT (in the same directory) to
determine which entries you need to add and remove.
* # config -r KERNELNAME
* # cd ../../compile/KERNELNAME
# make clean depend
# make all install
* # shutdown -r now
Obviously, the rest of the book goes in to much more detail.
> I think the terminology is just tripping me up, here: are these really
> separate books? Will these be toplevel Docbook "book" elements? I'm
> wondering if there exists enough material in each book to warrant a
> book, and thence a collection for all of our documentation.
I think they are. I started off by thinking that this could be one
big book, with each of these being 'parts' within that book (each part
composed of many chapters).
The more I thought about this, the more I thought that they may as well
be books in their own right. It makes them a little more standalone,
and means that the new user is not confronted with 580 pages of
documentation to read in one lump. In DocBook terms, we'd have the
FreeBSD documentation <set>, consisting of many <book>s.
Of course, with clever SGML tricks the chapters (and books) can be
agregated together in different ways, including producing one (big) book
that includes the content of all the others, if there's a demand for
that sort of thing.
> > [ new organization ]
>
> Okay, I'm warming up to the idea now. In particular, "Unix Basics"
> ought to be its own book. A Unix expert doesn't need all that extra
> material if s/he just wants to know how to install FreeBSD.
Yep.
> Finally, don't forget that we'll need a separate book that's a compiled
> index to the whole collection.
Yep. A technical issue more than an organisational one.
N
Byron Brummer
> * From: Bill Fumerola <bi...@chc-chimes.com>
> * My name is ambiguous even with a first name and last initial. Sigh.
>
> That's what you get by having such a generic (and evil) first name. :>
>
> -PW
> P.S. Have you tried "xbill"?
Port: xbill-2.0
Path: /usr/ports/games/xbill
Info: Save your computers from the evil clutches of Bill
I don't think we'd want to confuse the two. :-)
--
-Zenin (ze...@archive.rhps.org) From The Blue Camel we learn:
BSD: A psychoactive drug, popular in the 80s, probably developed at UC
Berkeley or thereabouts. Similar in many ways to the prescription-only
medication called "System V", but infinitely more useful. (Or, at least,
more fun.) The full chemical name is "Berkeley Standard Distribution".
Sue Blake
> On Tue, Apr 06, 1999 at 10:20:04AM -0600, Sean Kelly wrote:
>
> > I mostly agree. In particular, kernel configuration is one of out
> > better chapters in the current handbook.
Yep, it was the first thing I had to do after installing. It took days
and required a lot of other learning (unix, editing, ...) along the
way, but the kernel came together in the end just like it said.
> > Yet some amount of kernel
> > configuration appears in nearly all the other chapters: in networking on
> > setting up the kernel with an Ethernet controller; in printing on
> > setting up the kernel for parallel ports; etc.
>
> Yep. One of the things each book will need is a "_topic_ for the
> impatient". This is just bullet points that provide the minimal
> information for those that know what they're doing, and don't need
> handholding.
This is also something that is very important for those who know
little. You don't help a raw beginner by dumping everything you know
about a topic, no matter how much they might need to understand all
that stuff eventually. If they can't stand back and see it as a doable
whole, visually follow a path of few steps and see what they're working
towards, it becomes too much to take in. Take this for example:
> For Kernel Configuration this would be something like;
>
> * Make sure you've installed the kernel sources.
>
> * Copy /sys/i386/conf/GENERIC /sys/i386/conf/KERNELNAME, where
> KERNELNAME is the name you want for your new kernel.
>
> * Read the comments in GENERIC and LINT (in the same directory) to
> determine which entries you need to add and remove.
>
> * # config -r KERNELNAME
>
> * # cd ../../compile/KERNELNAME
> # make clean depend
> # make all install
>
> * # shutdown -r now
A lot of new people with no experience will need to have something like
the above to guide their reading of the full detail, or else they'll be
overawed and give up. If I look at that and don't understand any of the
steps, at least I can get some idea of what kind of steps they are and
how many parts I'll have to absorb before I get to the end. It is
necessary at the outset to be able to see the task as a whole.
Most people's brains can hold approximately seven pieces of information
together at one time. Familiar information groups itself so that one
can hold seven of these groups (or concepts), or seven tiny new pieces,
or a mixture. What we regard as one item might be ten or twenty to a
newcomer. We're writing instructions (docs) for hardware (brains) of a
type that we don't have access to any more.
For example, someone who knows absolutely nothing might temporarily
register the list above in their mind as:
1. Make sure that something with that funny name is installed.
2. Decide on a name for my kernel and copy some file that I've
never heard of to that new name (I think).
3. There's some task to do with adding and removing some things, and
there will be two files to read to help with these decisions.
4. Type a whole lot of unknown commands, probably need to be root.
5. Shut down the computer.
That's about as long as it can afford to be. Despite its look, this
rough list is enough to give a reference pathway through the ensuing
study, even though the original list didn't make a lot of sense. One of
those steps might take hours or days, especially if they need to detour
midway to learn more unix commands, look up hardware manuals, or to
experiment or ask questions when the documentation doesn't make sense.
Without having some concise overview of the steps it is very easy to
get lost or disheartened.
Contrast this with the typical many pages of carefully written text
which describe the finished outcome, start with background info,
deliver basic skills, specific skills, each task broken up into its
learnable subtasks, a multitude of little steps which are all easy but
far too many to see how they fit together in relation to the overall
goal. Plugging them together as you go is not enough on its own. That's
why build-it-yourself hobby kits come with a photo on the front of the
box and an exploded view on the back and deliver the tweezer-sized
pieces with instructions after breaking the shrinkwrap. Advanced people
don't need the bottom-up approach, people approaching something totally
new need to see it in *both* directions.
I have yet to find anything to do with FreeBSD that is not very easy to
do. It's just that there's always so many of these easy things to do!
It's not enough for novices to learn all the little steps. Unless they
can join those steps together into chunks of increasing size up to a
whole task, it'll always seem a lot harder than it is, no matter how
much explanation we pump into them. The two devices most useful here
are repeated real practice at appropriate stages, and having a concise
overview of the steps for reference from the outset.
If you're preparing documentation at different levels, please don't
write off the quick guide approach as only useful to those in the know.
For many learners it can make the difference between giving up and
giving it a go, even if they don't understand the items initialy.
--
Regards,
-*Sue*-
Bill Fumerola
> * My name is ambiguous even with a first name and last initial. Sigh.
>
> That's what you get by having such a generic (and evil) first name. :>
The number of references I get in relationship to my name and a certain
CEO is astronomical.
> P.S. Have you tried "xbill"?
Yes, and I like it. :->
- bill fumerola - bi...@chc-chimes.com - BF1560 - computer horizons corp -
- ph:(800) 252-2421 - bfum...@computerhorizons.com - bi...@FreeBSD.org -
To Unsubscribe: send mail to majo...@FreeBSD.org
Bill Fumerola
> Port: xbill-2.0
> Path: /usr/ports/games/xbill
> Info: Save your computers from the evil clutches of Bill
>
> I don't think we'd want to confuse the two. :-)
I think it's time for me to commit a clarification on just exactly which
Bill we're talking about. :>
Bill Fumerola
> OK, when you guys have *quite* finished :-)
>
> Anyone got any comments about the other 356 lines in my mail :-) ?
I guess I could go read it. :)
Seriously, I like the 'minibook' idea and would be willing to contribute
articles given a list that I could take bite-size projects.
ie, I would be willing to write little documents on how to set up typical
installations of named/bind, but wouldn't want to write the whole
networking minibook.
Bill Fumerola
> Yeah. One of the benefits of this approach is that it makes it easier
> to slot new material in, and at the same time simpler to hand off
> chunks to volunteers and say "Here's a complete framework, all it needs
> is content".
And the advocates of the lesser-known-but-loved-by-those-who-use-it
software would probably love to have something to dock their documentation
into.
Bill Fumerola
> But how do we induce people to fill in the old ignored bits, like the
> missing X section? Would it help to have a monthly posting to -doc
> listing what documentation is sorely lacking and what's currently being
> worked on?
The weekly 'Bugmaster' reports I(as do all committers) get mailed to us
saying "HEY! THESE ARE OPEN PRs!" motivate me everynow and then. I know
the ports list recieves open ports PRs, does the docs list recieve open
docs PRs?
Chad David
Sue Blake wrote:
> On Wed, Apr 07, 1999 at 10:31:24AM -0400, Bill Fumerola wrote:
> > On Tue, 6 Apr 1999, Nik Clayton wrote:
> >
> > > Yeah. One of the benefits of this approach is that it makes it easier
> > > to slot new material in, and at the same time simpler to hand off
> > > chunks to volunteers and say "Here's a complete framework, all it needs
> > > is content".
> >
> > And the advocates of the lesser-known-but-loved-by-those-who-use-it
> > software would probably love to have something to dock their documentation
> > into.
>
> Wow! Here's my big chance to write a "book" on ed :-)
>
> But how do we induce people to fill in the old ignored bits, like the
> missing X section? Would it help to have a monthly posting to -doc
> listing what documentation is sorely lacking and what's currently being
> worked on?
>
Aside from the extra burden of having to pick a new topic every month I
think that is a good idea. I have been just listening here for some time, and
I have never really gotten a feeling for what is requried, and when I asked I
was
told to listen in.... I am very busy but I often work on and document systems
(Coda, WMVare, IPv6/IPsec), and if there was a simple framework that I could
contribute them into then I would. Also if I knew what was requried I might get
ambitious every once in a while, and just write something because it is needed.
I will continue to listen in :).
Chad David.
>
> --
>
> Regards,
> -*Sue*-
Nik Clayton
> But how do we induce people to fill in the old ignored bits, like the
> missing X section? Would it help to have a monthly posting to -doc
> listing what documentation is sorely lacking and what's currently being
> worked on?
Keep lowering the barrier to contributing. At the moment, the Handbook
is probably a bit daunting. It's big, it's complex, you need to read
it if you want to write to it's style (such as there is one). What
you want to write might not fit in properly, or cross over some existing
sections.
By breaking it up in to chunks it should be an easier task to contribute
from the perspective of a potential author. I'm still working on the
primer, to make it easier for people to get up to speed on how to
contribute most effectively to the Doc. Proj. as well.
I'm also not averse to making it easy for other doc groups to stick
documentation in there. The GNOME and KDE folks are switching to
DocBook, as is the Linux Documentation Project as a whole. I'd be
*very* happy to see a consensus emerge as to a useful approach we
can share -- the vast majority of Linux or FreeBSD documentation is,
in fact, Unix documentation.
There's a couple of other messages about this from Lars posted today.
N
--
Bagel: The carbohydrate with the hole
Jeroen Ruigrok/Asmodai
> But how do we induce people to fill in the old ignored bits, like the
> missing X section? Would it help to have a monthly posting to -doc
> listing what documentation is sorely lacking and what's currently being
> worked on?
That's largely how freebsdzine.org works
We have a number of topics we think are interesting to write about, those
get written about and then there's a large number of people requesting a
certain topic which one of the regulars from Undernet's #FreeBSD or one of
the mailinglist authors picks up and tries to document.
Might work for the Doc Proj as well mayhaps?
---
Jeroen Ruigrok van der Werven <http://www.freebsdzine.org>
asmodai(at)wxs.nl The idea does not replace the work...
Network/Security Specialist <http://home.wxs.nl/~asmodai>
*BSD: Powered by Knowledge & Know-how <http://www.freebsd.org>
Sue Blake
> On Tue, 6 Apr 1999, Nik Clayton wrote:
>
> > Yeah. One of the benefits of this approach is that it makes it easier
> > to slot new material in, and at the same time simpler to hand off
> > chunks to volunteers and say "Here's a complete framework, all it needs
> > is content".
>
> And the advocates of the lesser-known-but-loved-by-those-who-use-it
> software would probably love to have something to dock their documentation
> into.
Wow! Here's my big chance to write a "book" on ed :-)
But how do we induce people to fill in the old ignored bits, like the
missing X section? Would it help to have a monthly posting to -doc
listing what documentation is sorely lacking and what's currently being
worked on?
--
Regards,
-*Sue*-
Steve Price
# The weekly 'Bugmaster' reports I(as do all committers) get mailed to us
# saying "HEY! THESE ARE OPEN PRs!" motivate me everynow and then. I know
# the ports list recieves open ports PRs, does the docs list recieve open
# docs PRs?
pe...@freebsd.org setup the cron jobs that do the mailings. You
might try asking him about them.
-steve
# - bill fumerola - bi...@chc-chimes.com - BF1560 - computer horizons corp -
# - ph:(800) 252-2421 - bfum...@computerhorizons.com - bi...@FreeBSD.org -
#
#
#
#