From mboxrd@z Thu Jan 1 00:00:00 1970 From: Dan Davison Subject: Re: A shorter manual Date: Thu, 29 Apr 2010 18:14:25 -0400 Message-ID: <87k4rpgb3y.fsf@stats.ox.ac.uk> References: <096F60B3-65ED-464E-8CDC-1041CA69B706@gmail.com> <4BD85AD3.9070807@ccbr.umn.edu> <87aasn1pa4.fsf@stats.ox.ac.uk> <87r5lygokh.fsf@stats.ox.ac.uk> <933E2206-FB3A-4202-A969-AE54CC12C950@gmail.com> Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable Return-path: Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.43) id 1O7c09-0004an-J6 for emacs-orgmode@gnu.org; Thu, 29 Apr 2010 18:14:33 -0400 Received: from [140.186.70.92] (port=40310 helo=eggs.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1O7c08-0004ac-2B for emacs-orgmode@gnu.org; Thu, 29 Apr 2010 18:14:33 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.69) (envelope-from ) id 1O7c05-0006UJ-Lr for emacs-orgmode@gnu.org; Thu, 29 Apr 2010 18:14:31 -0400 Received: from markov.stats.ox.ac.uk ([163.1.210.1]:40191) by eggs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1O7c05-0006U8-E9 for emacs-orgmode@gnu.org; Thu, 29 Apr 2010 18:14:29 -0400 In-Reply-To: <933E2206-FB3A-4202-A969-AE54CC12C950@gmail.com> (Carsten Dominik's message of "Thu, 29 Apr 2010 23:27:42 +0200") List-Id: "General discussions about Org-mode." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org@gnu.org Errors-To: emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org@gnu.org To: Carsten Dominik Cc: Matti De Craene , emacs org-mode mailing list Carsten Dominik writes: > On Apr 29, 2010, at 7:23 PM, Dan Davison wrote: > >> Carsten Dominik writes: >> >>> On Apr 28, 2010, at 8:43 PM, Matti De Craene wrote: >>> >>>>> - 2.8 Drawers >>>>> - 3.2 Column width and alignment >>>>> - 3.3 The Spreadsheet (4 rather technical pages) >>>>> - 7.4 Property Inheritance and 7.5 Column View >>>>> (do beginners really need properties at all ??) >>>> >>>> >>>> I would agree on this list (except maybe drawers). >>>> >>>> If there is room for additional sections maybe: >>>> - include the org ref card as an appendix (which in itself offers a >>>> very good overview of org) >>>> - include some pointers into getting emacs for different OSes and >>>> getting started with emacs. If there would be an O=C2=B4Reilly book on >>>> Org-mode this would be in the first chapter or so. For people who >>>> started using emacs because of org (like me) the current >>>> Introduction >>>> might still be too cryptic (?) >>> >>> Hi Dan, Matti, >>> >>> I think I agree, just cannot easliy let go of the spreadsheet >>> as a core feature - you caught me there :-), and you are right, also >>> >>> I would be very glad to hand over the control over this document >>> to either of you or to another volunteer. >> >> Hi Carsten, >> >> I'm afraid I don't want to take responsibility for this (a predictable >> position). > > Sure, I understand. > >> Apart from anything else there are several areas of Org >> that I don't know enough about. If there isn't a volunteer, perhaps we >> could place this document on Worg, and someone could periodically >> review >> the changes and judge whether they should be applied to the master >> copy >> on the Org website? We could request on this list volunteers for >> someone >> to make specific entries (e.g. adding a "Further reading" section >> for a >> specific chapter). > > Hmmm, I am not sure how efficient this would be. > > I have it now down to 40 pages, with live links to the manual and to > tutorials at the end of each chapter... > > http://orgmode.org/orgguide.pdf That looks great. Having the links to Worg and other tutorials is really nice. I noticed a couple of typos in the live links: - p.29 in John Wiegely's name - p.36 "persentation" and to split hairs - p.33 "from the manual" -> "of the manual" for consistency Dan > > I guess I am done here - a volunteer con still take this up... > > - Carsten > >> >> Dan >> >> >>> Maybe then we could >>> make something really nice out of this experiment - I will not >>> be able to spend much more time on it.... >>> >>> - Carsten >>> >>>> >>>> >>>> -- >>>> >>>> Matti >>>> >>>> >>>> >>>> >>>> On Wed, Apr 28, 2010 at 7:05 PM, Dan Davison >>>> wrote: >>>>> Erik Iverson writes: >>>>> >>>>>> Carsten Dominik wrote: >>>>>>> Dear all, >>>>>>> >>>>>>> with the Org-mode manual moving toward 200 pages, I am >>>>>>> starting to worry that people with stop in their tracks >>>>>>> when considering Org-mode, just because of the sheer size >>>>>>> of the manual. >>>>>>> >>>>>>> So I did a little experiment. I took the manual and stripped >>>>>>> everything which could be considered advanced material, but >>>>>>> keeping all features and all basic commands and customizations. >>>>>>> >>>>>>> What remains are about 50 pages. A document with the same >>>>>>> structure (even the same chapter numbers) as the manual. >>>>>>> I am wondering if it would be useful to have this as a beginners >>>>>>> document - or if the existence of this document would lead >>>>>>> to more confusion than relief. >>>>>>> >>>>>>> http://orgmode.org/orgguide.pdf >>>>>>> >>>>>>> I don't see this a an alternative for the manual - just >>>>>>> as an additional, rather static document, with little need for >>>>>>> updates. The manual would continue to be the comprehensive >>>>>>> and constantly updated document. >>>>>>> >>>>>>> Comments are welcome. >>>>> >>>>> Hi Carsten, >>>>> >>>>> I think this would be a good thing to have. >>>>> >>>>> It would be good to have active HTML links to the relevant main >>>>> manual >>>>> sections in PDF and HTML versions. (even if this is not >>>>> encouraged by >>>>> texinfo format). >>>>> >>>>> I'm tempted to suggest going even a little further than you have >>>>> done. >>>>> If you were to make it shorter, I would suggest removing the >>>>> following >>>>> sections, and to replace removed sections with very short non- >>>>> technical >>>>> advertisements for features that are covered in the main manual. >>>>> >>>>> - 2.8 Drawers >>>>> - 3.2 Column width and alignment >>>>> - 3.3 The Spreadsheet (4 rather technical pages) >>>>> - 7.4 Property Inheritance and 7.5 Column View >>>>> (do beginners really need properties at all ??) >>>>> >>>>> Dan >>>>> >>>>>> >>>>>> I think it's a great idea. The R project has something called "An >>>>>> Introduction to R" for beginners, separate from the complete >>>>>> manual. >>>>>> I think that as a beginner, and wondering how to break into >>>>>> learning a >>>>>> new package, that "reading the manual" has certain negative >>>>>> psychological connotations that "reading the intro document" does >>>>>> not, >>>>>> not the least of which is the length of full manual. >>>>>> >>>>>> And since knowing just the basics of org can be immensely >>>>>> beneficial, >>>>>> I think it's even more reason to have a basic intro document. >>>>>> >>>>>> --Erik >>>>>> >>>>>> >>>>>> _______________________________________________ >>>>>> Emacs-orgmode mailing list >>>>>> Please use `Reply All' to send replies to the list. >>>>>> Emacs-orgmode@gnu.org >>>>>> http://lists.gnu.org/mailman/listinfo/emacs-orgmode >>>>> >>>>> >>>>> _______________________________________________ >>>>> Emacs-orgmode mailing list >>>>> Please use `Reply All' to send replies to the list. >>>>> Emacs-orgmode@gnu.org >>>>> http://lists.gnu.org/mailman/listinfo/emacs-orgmode >>>>> >>> >>> - Carsten >>> >>> >>> >>> >>> >>> _______________________________________________ >>> Emacs-orgmode mailing list >>> Please use `Reply All' to send replies to the list. >>> Emacs-orgmode@gnu.org >>> http://lists.gnu.org/mailman/listinfo/emacs-orgmode > > - Carsten > > > > > > _______________________________________________ > Emacs-orgmode mailing list > Please use `Reply All' to send replies to the list. > Emacs-orgmode@gnu.org > http://lists.gnu.org/mailman/listinfo/emacs-orgmode