From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: ken Newsgroups: gmane.emacs.help Subject: Re: emacs documentation: what's active voice, passive voice? Date: Fri, 10 Dec 2010 11:04:29 -0500 Message-ID: <4D024F8D.8060707@mousecar.com> References: <4ca8659e$0$50453$14726298@news.sunsite.dk> <322eca01-3bf5-4078-9439-57ba9503afc6@k1g2000prl.googlegroups.com> <87aakee8bm.fsf@gmail.com> Reply-To: gebser@mousecar.com NNTP-Posting-Host: lo.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=ISO-8859-15 Content-Transfer-Encoding: 7bit X-Trace: dough.gmane.org 1292002596 20928 80.91.229.12 (10 Dec 2010 17:36:36 GMT) X-Complaints-To: usenet@dough.gmane.org NNTP-Posting-Date: Fri, 10 Dec 2010 17:36:36 +0000 (UTC) To: help-gnu-emacs@gnu.org Original-X-From: help-gnu-emacs-bounces+geh-help-gnu-emacs=m.gmane.org@gnu.org Fri Dec 10 18:36:31 2010 Return-path: Envelope-to: geh-help-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([199.232.76.165]) by lo.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1PR6tO-0007Xv-NA for geh-help-gnu-emacs@m.gmane.org; Fri, 10 Dec 2010 18:36:27 +0100 Original-Received: from localhost ([127.0.0.1]:60401 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1PR6tN-00073Z-C1 for geh-help-gnu-emacs@m.gmane.org; Fri, 10 Dec 2010 12:36:25 -0500 Original-Received: from [140.186.70.92] (port=42773 helo=eggs.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1PR5SW-0007ga-U8 for help-gnu-emacs@gnu.org; Fri, 10 Dec 2010 11:04:37 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1PR5SU-0004q3-Kb for help-gnu-emacs@gnu.org; Fri, 10 Dec 2010 11:04:36 -0500 Original-Received: from mout.perfora.net ([74.208.4.194]:60254) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1PR5SU-0004pl-GI for help-gnu-emacs@gnu.org; Fri, 10 Dec 2010 11:04:34 -0500 Original-Received: from dellap.mousecar.net (dsl093-011-016.cle1.dsl.speakeasy.net [66.93.11.16]) by mrelay.perfora.net (node=mrus4) with ESMTP (Nemesis) id 0M1WUr-1QKPvq0jjl-00tO1q; Fri, 10 Dec 2010 11:04:32 -0500 User-Agent: Thunderbird 2.0.0.24 (X11/20101126) In-Reply-To: <87aakee8bm.fsf@gmail.com> X-Enigmail-Version: 0.96.0 OpenPGP: id=5AD091E7 X-Provags-ID: V02:K0:5heyqiTXssKbv4D8X8cDDk10VFYGRjOiONWrYMB2hq6 inXsOBpqBRCeYeF/ViPGC8Zyrty3NCuBlozj1A5vyhhlF9FRKx 0bgu4K7XngkoigO5XDty+GV31atC+dmHZtvL4j5ju2VWFbHcSb oIpUoFVVcd1eBXg2Aawau8oKqUrJVxyvvgcfM9RUXBiRxNPUDF w8YSoJgqkGjOoaJY3F049UPB9wJ2Fx+FvYIj+lMqy0= X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-BeenThere: help-gnu-emacs@gnu.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: Users list for the GNU Emacs text editor List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Original-Sender: help-gnu-emacs-bounces+geh-help-gnu-emacs=m.gmane.org@gnu.org Errors-To: help-gnu-emacs-bounces+geh-help-gnu-emacs=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.help:77400 Archived-At: 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.