[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: emacs documentation: what's active voice, passive voice?
From: |
ken |
Subject: |
Re: emacs documentation: what's active voice, passive voice? |
Date: |
Fri, 10 Dec 2010 11:04:29 -0500 |
User-agent: |
Thunderbird 2.0.0.24 (X11/20101126) |
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.
- emacs documentation: what's active voice, passive voice?, Xah Lee, 2010/12/08
- Re: emacs documentation: what's active voice, passive voice?, Uday Reddy, 2010/12/08
- Re: emacs documentation: what's active voice, passive voice?, Alan Mackenzie, 2010/12/08
- RE: emacs documentation: what's active voice, passive voice?, Drew Adams, 2010/12/09
- Re: emacs documentation: what's active voice, passive voice?, Sean Sieger, 2010/12/09
- Re: emacs documentation: what's active voice, passive voice?,
ken <=
- Re: emacs documentation: what's active voice, passive voice?, Russ P., 2010/12/09
- Re: emacs documentation: what's active voice, passive voice?, David Combs, 2010/12/08
- Re: emacs documentation: what's active voice, passive voice?, Stefan Monnier, 2010/12/08
- Re: emacs documentation: what's active voice, passive voice?, Pascal J. Bourguignon, 2010/12/08
Re: emacs documentation: what's active voice, passive voice?, Bruce Stephens, 2010/12/08
Message not available