[FM Discuss] RTFM? How to write a manual worth reading

[Gregory Pittman]

On 05/14/2015 10:35 AM, Mark Hancock wrote:
> It's good to have as a reminder to practice good writing though.
> Sometimes i think that all these problems would be solves with better
> writing skills being put to use.
> 
> Now... what are better writing skills?
> 

Good writing is good writing.
This article has a nice conversational style, quite typical for web and
other journalism. A lot of the parts are rather empty of useful
information, for example Start Here - Reference Guide - Tutorials:
pretty generic stuff.

He doesn't like the odd references to Monty Python in the Python
documentation, so what does he do? Includes a video of the Dead Parrot
sketch. My biggest complaint about the examples in the Python
documentation is that they tend to be too trivial for much learning. In
contrast, I think Larry Wall's example writing about Perl is both
entertaining and informative.

He alludes to good documentation spending time on good examples of usage
rather than bad. Look how much space was used showing what not to do in
documentation, and the positive advice is more like words to live by.

Greg