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

[Mike Davis]

I want to start off by saying thank you to all those who are responsible for 
Samba. It is a fantastic application which I'm sure has only been made 
possible by a lot of hard work with not much to show in return accept for 
some personal satisfaction and the occasional word of praise and thanks. 
Kudos to all.

I am new to Samba and not a programmer, but want to help, and have 20 years 
of computer experience. Since I am new to Unix/Linux , I AM reading lots of 
books, man pages, docs and reading them slowly. While doing this, I am 
finding the odd typo or spelling error. Now the dilema is: on the one hand I 
am probably a good source for catching errors because I NEED to go through 
the documentation slowly and repetitively to understand it while those in 
the know only scan the docs as reference material. On the other hand, it is 
consuming a lot of my time just to learn about Samba and how to configure 
Linux so I don't have time (yet) to learn about CVS, 'diff', etc. (I'm not 
even sure that these are the preferred methods for notifying someone of a 
correction) Or put another way, I still don't have enough experience to know 
how to inform the people who work on a project that I have found an error 
(and there are many projects which I have been introduced to over the last 
year, presumably each group having their own prefered method of contact).

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 
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 
honest I was hesitant because I don't honestly know what the programming 
term "patch" means and if it applies to correcting grammar or spelling. I 
only continued with this editorial comment because I found the errors intact 
in the http://www.samba.org/samba/docs/ documents.

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.

Having said that, this post got sent here, because I read the following:
"If you have an idea for a patch but can't write the code for some reason 
then discuss it on the Samba mailing list and try to find someone else who 
can work up a patch. If you send your idea here it will be deleted. " mind 
you the link is to http://lists.samba.org/ and does not explicitly say which 
of the 27 possible lists a message should be sent to -  most of them are of 
course not candidates.

If I am sending this to the wrong list, I appoligize for the intrusion. My 
intentions were not only good, but I believe that others may be willing to 
help if it was easy enough for them to do so. I spent quite some trying to 
figure out what was the prefered way to report the few little mistakes that 
I have found -- including contacting a programming friend who suggested 
"don't worry about it" -- and short of learning about 'diff' could not find 
the answer to my question.

Suggestions:
1) Make it clear where the active documents are (those that are eligable for 
correction).
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 :-) )
; I appreciate that you are bound to get all sorts of wacky emails that 
don't pertain to the material at hand, or are staring the user right in the 
face, or tell you what the mistake was but not in which document (I'm hoping 
that this post doesn't fall into ALL of these pitfalls ;-) )...
I could go on -- about how I'm sure you have better things to spend your 
time on rather than a missing letter here or there, and how its not worth 
lossing ones shit over ... oops I mean shirt ... but I think I have said 
enough.

Keep up the good work one and all. Love that Samba!!
Mike Davis  :-))

PS. Please forgive any typos or spelling erors ;-) you may find in this 
message.

--- Minor corrections I have found
1) http://www.samba.org/samba/docs/man/smbpasswd.5.html
"Each field ithin each line" should be "Each field within each line"
2) http://www.samba.org/samba/docs/man/smbpasswd.8.html
"password will beed to be manually" should be "password will need to be 
manually"
3)UNIX_INSTALL.txt  and the HTML version
(eg http://de.samba.org/samba/ftp/docs/textdocs/UNIX_INSTALL.txt)
(and http://samba.org/samba/ftp/docs/htmldocs/Samba-HOWTO-Collection.html)
"Your should get back a list of" should be  "You should get back a list of"
[This one is dated Apr 2002 and specifically mention Jerry Carter 
jerry at samba.org, so I will CC him a copy of this note -- especially since 
his name seems to be everywhere within the Samba Doc stuff that I found -- 
where do you get the time? Keep up the excellent work.]



_________________________________________________________________
Send and receive Hotmail on your mobile device: http://mobile.msn.com