How can I help make the docs better? (When I'm too green to know how?)
mike2000jan at hotmail.com
Tue May 14 23:01:15 GMT 2002
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.
1) Make it clear where the active documents are (those that are eligable for
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
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
--- Minor corrections I have found
"Each field ithin each line" should be "Each field within each line"
"password will beed to be manually" should be "password will need to be
3)UNIX_INSTALL.txt and the HTML version
"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
More information about the samba-docs