Hi Steve
Is this the documentation that you are referring to that needs
improvement:
http://rubyforge.org/docman/view.php/632/233/posted-docs.index.ht
ml
Please help me out and post some comments on what you like and
don't like. I am still making improvements in the docs.
Hi Jim,
I'm pretty sure those are the docs I couldn't fathom. IMHO what you
need is a quickstart -- all code, no theory. Start with the
simplest possible program that the user can paste into his editor
and then give him the command line to run, and show the expected
output.
I think the idea is to get the user to say "hey, I can do this".
Once he's hooked, he has incentive to dig into the incredibly rich
array of tools you offer.
Personally, when I write documentation on Troubleshooters.Com, I
always start with a "Hello World" and then, one feature at a time,
I move from the known to the unknown (my wife's a teacher
.
Another thing. I usually show full programs (in blue background) so
the user can paste them into his editor and run them immediately,
and then the expected results in yellow background so the user can
compare his results to the expected results. Once the user sees
both the code and the results, he can then figure out why it works
like it does, and he can also experiment with the code to learn
even more.
For an example of how I write my documentation, see this:
http://www.troubleshooters.com/codecorn/ruby/basictutorial.htm
Please keep in mind that I'm displaying this as an example of my
documentation methods, not as an example of particularly good Ruby
documentation. I wrote most of this material with less than a
week's Ruby experience, and before I signed up with this mailing
list. In fact, a companion document called "Ruby the Right Way" was
my reason for my "They say I write Ruby like Perl" post.
If any of you have the book "Samba Unleashed", the chapters with my
name on them are another good example of my documentation methods.
In summary -- IMHO a quickstart would be the catalyst to greater
acceptance of OptionParser. Use whole but tiny programs, without
error checking and the like, to make your points. That way the user
can cut and paste right onto his box and follow your examples on
his own. Within 10 minutes the user understands the power of
OptionParser and is ready to learn more.
Thanks
SteveT
Steve Litt
http://www.troubleshooters.com
(e-mail address removed)