I am beginning to think of documentation as a burden. Not for me, for
the readers. Yes, people do need docs, but the *last* thing they need
is to wade through endless words words words.
As I rewrite the rst chapter I wonder, "Who wrote this shit?" Oh yeah,
I did :-)
Imo, we must avoid duplicate words in the docs. True, we may need an
intro, and possibly a summary, but these should have as *little*
detail as possible. The Nutshell page has almost no technical
details; the rst chapter should give most details exactly once.
Earlier this year I got excited about stories. I still am, but now I
want haiku-like stories, not war-and-peace-like stories. For example,
in rewriting the Reference chapter, the discussion of various @<file>
nodes often has this form:
When reading @x trees, Leo does such-and-such.
When writing @x trees, Leo does so-and-so.
These are mini-stories. Not as moving as Ernest Hemingway's 6-word
short story, "For sale: baby shoes, never worn.", but effective :-) In
stories *somebody does something*, and that almost completely
eliminates passive voice.
Edward
P.S. It's amusing to see how many sentences in this post are mini-
stories, or contain a mini-story in a phrase or clause.
EKR
--
You received this message because you are subscribed to the Google Groups
"leo-editor" group.
To post to this group, send email to [email protected].
To unsubscribe from this group, send email to
[email protected].
For more options, visit this group at
http://groups.google.com/group/leo-editor?hl=en.
