Fixing the documentation
Joe Rhett
jrhett at isite.net
Sun Aug 19 21:07:42 GMT 2001
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