Re: emacs documentation: what's active voice, passive voice?

[ken <gebser@mousecar.com>]

On 12/09/2010 08:16 PM Sean Sieger wrote:
>     There is no royal road to writing, like Math.  To write better, read more.
>     Read, re-read, re-re-read, and read better what you've written (and
>     rewritten...).
> 
> Right?  
> 
> I always thought `reading is miswriting and writing is misreading'
> instructive.

Good advice.  And it applies to a lot more technical documentation than
just what's done for emacs.

There's a very old saying among writers: Writing is rewriting.  Yeah,
that means more time and work than just dashing off a first draft.  But
the benefits are worth it.

One technique for better documentation is to give your first draft to a
newbie and have him/her work from it.  That newb will notice any holes
or ambiguities and other failures in the text; these are then added into
the doc.  This amended doc would then be passed on to another newb and
the process repeats repeats until a newb has no more questions or
failures.  A wiki is a good platform for this kind of process.