Re: Writing Good Documentation

The one thing that there is almost never enough of is examples. Simple examples... complex examples... complete working examples... If it's got a feature, don't just "document" it, show us an example. If there's more than one way to do something, show us an example of each. No amount of verbage can replace a good working example. In fact, if you have to choose between writing long paragraphs describing in detail the reasons behind each design decision or writing a few good examples, write the examples.

Did I mention that I like examples?

()-()
 \"/
  `

Comment on Re: Writing Good Documentation

Replies are listed 'Best First'.
Re: Re: Writing Good Documentation by jepri (Parson) on Jun 25, 2002 at 03:41 UTC
Totally agreed. This is what set Perl apart for me, compared to other languages. When I first started using perl, and found the help system, it very nearly blew my little mind. I was left staring at the screen going "easy.. too.. use... can't.. cope.. Whoopee!". This is after struggling with horrible C documentation like 5. Go to the src subdirectory and look at the top of topten.c. You m +ay want to change the definitions of PERSMAX and PERS_IS_UID here to get d +ifferent behavior from the high score list. 6. Edit the top sections of the src and util Makefiles. (If you are +doing a full recompile, or if you got your files from someplace besides +the official distribution, type 'touch makedefs.c' to make sure certai +n files (onames.h, pm.h) get remade instead of relying on the potentially troublesome timestamps.) [download] Thesedays all my code comes with examples, and where possible, a base configuration that will work on nearly all machines. ____________________ Jeremy I didn't believe in evil until I dated it.	[reply] [d/l]
Re: Re: Writing Good Documentation by blackjudas (Pilgrim) on Jun 25, 2002 at 17:26 UTC
Absolutely 100% agreed. I cannot go forth from documentation written by someone who assumes the verbage provided gives enough information in one place to make good use of it. Learning Perl is my one prime example, the documentation provided (once you're used to the semantics) is indispensible, but at times confusing, the examples provided are excellent but may not apply to the issue at hand. I found myself trying to find definitions for words used in the documentation. Feeling completely at odds with it, I found Perl Monks and the rest is history. Examples of any kind are your friend, supply novice, intermediate and expert examples then try to mix it up. This may make your documentation larger but I think it would appeal to a larger audience. BlackJudas	[reply]
Re: Re: Re: Writing Good Documentation by ignatz (Vicar) on Jun 25, 2002 at 17:41 UTC
I've been very impressed with the way Bruce Eckel deals with it in his books. All of the examples are automatically built so that he can veryify that they actually compile. Makes me start to think about a test/example system where the examples of a script are also some of it's tests. That way as you change your code the tests don't just point out errors in code but also where you need to update your examples to reflect changes in the code. Hmmmm....... ()-() \"/ `	[reply]


Perl: the Markov chain saw
	PerlMonks