From mboxrd@z Thu Jan 1 00:00:00 1970 From: Ciaran Mulloy Subject: Re: template for writing Emacs manuals in Org Date: Thu, 19 May 2016 00:59:26 +0100 Message-ID: <87zirmc3z5.fsf@gmail.com> References: <87eg955clk.fsf@ericabrahamsen.net> <87wpmt7u5i.fsf@gmx.us> <87a8jph6ry.fsf@ericabrahamsen.net> <87inyd8gkl.fsf@ericabrahamsen.net> <87d1okbyx5.fsf@russet.org.uk> Mime-Version: 1.0 Content-Type: text/plain Return-path: Received: from eggs.gnu.org ([2001:4830:134:3::10]:55827) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1b3BNQ-0002WU-8V for emacs-orgmode@gnu.org; Wed, 18 May 2016 19:59:48 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1b3BNK-0004EK-9N for emacs-orgmode@gnu.org; Wed, 18 May 2016 19:59:43 -0400 Received: from plane.gmane.org ([80.91.229.3]:60644) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1b3BNK-0004ED-2W for emacs-orgmode@gnu.org; Wed, 18 May 2016 19:59:38 -0400 Received: from list by plane.gmane.org with local (Exim 4.69) (envelope-from ) id 1b3BNI-0005SQ-No for emacs-orgmode@gnu.org; Thu, 19 May 2016 01:59:36 +0200 Received: from 212.17.38.143 ([212.17.38.143]) by main.gmane.org with esmtp (Gmexim 0.1 (Debian)) id 1AlnuQ-0007hv-00 for ; Thu, 19 May 2016 01:59:36 +0200 Received: from crmulloy by 212.17.38.143 with local (Gmexim 0.1 (Debian)) id 1AlnuQ-0007hv-00 for ; Thu, 19 May 2016 01:59:36 +0200 List-Id: "General discussions about Org-mode." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org@gnu.org Sender: "Emacs-orgmode" To: emacs-orgmode@gnu.org I'm coming a little late to this thread so apologies! Most of the previous thread has focused on analysing the various pros and cons of the various documentation methods, INFOText/html/org, to produce the final documentation. I would like to suggest that whatever method is used that it also supports the development workflow cycle of emacs. Core features that are documented should also have corresponding testplans. John Wiegley makes this point in his in his YouTube talk with Sacha Chua https://www.youtube.com/watch?v=nUjgKoOYxos. He concisely summed up the workflow issue as 'bugs/tests/documentation'. It was one of the areas that needed more effort. The challenge is to elegantly manage the documentation process so that it caters for the complete workflow development cycle. I favour the use of org as it has the capability of embedding tests within the documentation, among other things. Ciaran