Fixing the documentation

Sean P. Elble S_Elble at yahoo.com
Sun Aug 19 21:28:22 GMT 2001


There are a lot of problems in the Samba docs; I plan on writing some new
stuff, but Gerald Carter recommened sending in your mods as a diff to the
SGML source. I use Samba because my clients are Windows, and I use HTML for
docs . . . oh well. I'll be sure to post when some of my docs are ready.

--------------------------------------------
Sean P. Elble
Editor, Writer, Co-Webmaster
MaximumLinux.org
http://www.maximumlinux.org/
elbles at maximumlinux.org
--------------------------------------------
----- Original Message -----
From: "Joe Rhett" <jrhett at isite.net>
To: "Gerald Carter" <gcarter at valinux.com>
Cc: <samba-technical at lists.samba.org>
Sent: Sunday, August 19, 2001 5:07 PM
Subject: Fixing the documentation


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





More information about the samba-technical mailing list