Fixing the documentation

[Gerald Carter]

On Sun, 19 Aug 2001, Joe Rhett wrote:

> 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.

Cause the DOMAIN.SID was never released in a production version
of Samba.  Sounds like you were using an old cvs version.

> 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?

Submit them to me <jerry at samba.org> against the SGML/DocBook source
(docs/docbook/*).  Don't diff against the HTML files for sure.

>
> 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.. )

The DocBook source is used to generate HTML and the the PDF file from the
HTML source.  So I'm not sure what you mean here.

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

Would love to see this.

> 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.

It is designed as a collection of HOWTO's.  Not as a book.  The idea is to
allow individuals to create a single chapter and havce it included in the
collection.  If someone would like to take on the role of editor and make
it more continuous that would be appreicated.

> 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.

Actually, i spoke with someone last week who still had WfWg on the
network.  We cannot release a version of Samba that doesn't support DOS
clients without hearing screams.







cheers, jerry
 ---------------------------------------------------------------------
 www.valinux.com         VA Linux Systems       gcarter_at_valinux.com
 www.samba.org              SAMBA Team              jerry_at_samba.org
 www.plainjoe.org                                jerry_at_plainjoe.org
 --"I never saved anything for the swim back." Ethan Hawk in Gattaca--