Fixing the documentation

[Joe Rhett]

I just got my first chance to play with 2.2 in quite a while, so I got the
latest CVS and went through the installation process on Friday. Install and
configuration was easy, but ...

1. Documentation exists in 3 places (at least). 

2. Most of it is redundant, lots of it is outdated, and none is complete.

3. There is no clear pointer about where to start. Eventually I figured out
that the .PDF in the root was the best place to start, but ...

Granted that I've done enough Samba installs that I could have done it
without the documentation, but I was wary of changes that obsoleted or
modified functionality (since I was updating a production server with an
existing configuration).

So my questions are:

1. Why isn't there a document for upgrading from 2.0.x to 2.2.x ?
	Changes like ${DOMAIN}.SID to MACHINE.SID aren't documented anywhere.
	Several little changes to smb.conf are worth noting.
	..had this document existed, I could have saved 4 hours of time.

2. Why is the documentation so disjointed and incomplete?

I am willing to take on the task of unifying the existing documentation.
How should I go about doing this? How would I submit updates?

If I took this on, I would probably want to:

1. Do the complete documentation set in HTML. PDF is nice, but PDF readers
aren't always available and there is A LOT of documentation that isn't always 
relevant ( WfWG, cluster.. )

2. Create a quick upgrade document for existing sites that don't need to
enable new functionality, just update the code.

3. Make the PDF be a good starting document easy to print, but contain
references to the HTML as a complete documentation source. The PDF is
a bit disjointed at the moment, trying to cover many topics and still
missing some basic essentials.

4. Move all references to Windows for WorkGroups to a separate section.
This isn't relevant to any installation I've seen in over 6 years. This
would prevent confusion and many FAQs on the mailing list, while providing
a single clear document of the changes necessary for Windows for Workgroups
support.
 
Note that I'm offering to clean up the documentation, not write new
documentation (although I will update some sections that could be clarified).
I've got an international flight on Tuesday. If you can tell me how to get
it and what you want, I can probably complete it during that flight and
submit on Wednesday morning.

-- 
Joe Rhett                                                      Chief Geek
JRhett at ISite.Net                                      ISite Services, Inc.