How can I help make the docs better? (When I'm too green to know how?)

[Gerald Carter]

On Tue, 14 May 2002, Mike Davis wrote:

> so I don't have time (yet) to learn about CVS, 'diff', etc. 

This docs list is a good point of contact.  I generally 
act as the CVS check in point, but there are several others 
working on updates, correcttions, etc...

CVS is not perfect, but probably very simple for what you 
need to be able to do.  See http://samba.org/samba/cvs/html
for details on obtaining Samba cvs code.  Diff's against release
code is also ok because the docs don't tend to be a moving target 
as much as the source code is.

For submitting patches, mt preferred method is

	diff -u oldfile newfile > newfile.diff

and send as an attachment.  It is better IMO to place the diff on
an FTP server so as to save bandwidth on the list but its not a strict 
rule.  Also I like patches as attachments better than inline because
the latter notmally converts tabs to spaces and is annoying when trying
to apply the patch.


> I don't want to wast anyones time (yours or mine) by reporting things that 
> have already been fixed, but I went to www.samba.org and it wasn't apparent 
> (to someone new that is since its always easy once you've been shown how to 
> do something) where I could find the work-in-progress files (ie. the MOST 
> up-to-date files). I assumed if I could find these then I could see if 

Anything that is wrong jis fair game :-)

> someone else has already corrected the mistakes I have found. The documents 
> themselves, while giving credit to those who worked on them, did NOT have a 
> contact email address which actually surprised me (two examples noted below 
> are 'man' pages). I did find http://samba.org/samba-patches/ and looked at a 
> few of the messages to see if this was the right place but it seemed like it 
> was more for programmers who had patches that would correct code not a 
> simple grammer or spelling error (which is all I have to offer). To be 

Our patch submission/bug tracking system could use some more maintaince.  
Simo has been doing a good job, but it is really bigger than one person.
What you did here weas fine (and appreciated).

> Bottom line, if it isn't quite obvious how to report a document mistake,
> then the people who are mostly reading them - the neophytes, like me -
> are not going to help out in the small way that we can.

That's probably our fault then.  We should provide more helpful 
information to encourage people to correct mistakes in our docs.

> Suggestions:
> 1) Make it clear where the active documents are (those that are eligable for 
> correction).

Everything except for textdocs/outdated/ should be up for grabs.

> 2) In the appropriate place add a page that gives a link to more detailed 
> instructions about how to help (I know easier said then done isn't it :-) )

Duely noted.  Will look into this.

> Keep up the good work one and all. Love that Samba!!

Thanks for the updates Mike.  :-)






cheers, jerry
 ---------------------------------------------------------------------
 Hewlett-Packard                                     http://www.hp.com
 SAMBA Team                                       http://www.samba.org
 --                                            http://www.plainjoe.org
 "Sam's Teach Yourself Samba in 24 Hours" 2ed.      ISBN 0-672-32269-2
 --"I never saved anything for the swim back." Ethan Hawk in Gattaca--