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

[Kai Blin]

* Mike Davis <mike2000jan at hotmail.com> [14/05/02, 23:01:15]:
> 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.

Congrats, this really shows you're an old school computer user. It's
hard to find those nowadays.

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

This is only too true. *sic* I've not been around for a while, but IIRC
not everybody gets developers access to the cvs repository. I recall
that I learned how to use diff just to send some corrections for typos
on the web page, too. ;)

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

Well, this might be an issue. The samba-docs mailing list should be
mentioned in there I think, since it's the place where these things
should be done.


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

Well, thanks anyway. It's more work than others would have put into it,
since it's "just a spelling/grammar error". See some programmers, they
will second your friend. ;)

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

We get worse here, like people sending mail that should go to the samba
list to this list here..  We'll survive that, I guess. (Flame /dev/null
if you think different)

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

It's said he's using clones.. but don't tell anybody.. ;)
People like him are the driving force of free software development.

Cheers, Kai

-- 
Kai Blin, private email
One organism, one vote.