From mboxrd@z Thu Jan 1 00:00:00 1970 From: Matt Lundin Subject: Re: Documentation wishlist items Date: Wed, 16 Sep 2009 08:46:57 -0400 Message-ID: <874or3njjy.fsf@fastmail.fm> References: <9cd2f5ff0909151421r25e4c7afn8d609e76e2462193@mail.gmail.com> <87tyz3a83l.fsf@gmx.de> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Return-path: Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.43) id 1Mntpm-0004PD-TU for emacs-orgmode@gnu.org; Wed, 16 Sep 2009 08:42:07 -0400 Received: from exim by lists.gnu.org with spam-scanned (Exim 4.43) id 1Mntpf-0004MY-Cm for emacs-orgmode@gnu.org; Wed, 16 Sep 2009 08:42:04 -0400 Received: from [199.232.76.173] (port=47765 helo=monty-python.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1Mntpe-0004Lt-Nx for emacs-orgmode@gnu.org; Wed, 16 Sep 2009 08:41:58 -0400 Received: from mx20.gnu.org ([199.232.41.8]:43756) by monty-python.gnu.org with esmtps (TLS-1.0:RSA_AES_256_CBC_SHA1:32) (Exim 4.60) (envelope-from ) id 1Mntpe-0002FS-5Z for emacs-orgmode@gnu.org; Wed, 16 Sep 2009 08:41:58 -0400 Received: from out1.smtp.messagingengine.com ([66.111.4.25]) by mx20.gnu.org with esmtp (Exim 4.60) (envelope-from ) id 1Mntpd-00045S-B4 for emacs-orgmode@gnu.org; Wed, 16 Sep 2009 08:41:57 -0400 In-Reply-To: <87tyz3a83l.fsf@gmx.de> (Sebastian Rose's message of "Wed, 16 Sep 2009 05:20:30 +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: Sebastian Rose Cc: emacs-orgmode Sebastian Rose writes: > Ethan writes: >> Hi guys, >> > Documentation is not such an easy thing to do and a lot of work, too. A > tutorial _is_ missing. We had some discussions here about that, but no > one got around to it. I think about it every so often, but writing a > tutorial is such a big thing to do. > > Personally, I think that one or two fictive characters would fit > best. People, simply using Org-mode to take notes, plan, publish and so > on. > > The entire thing should start _very_ simple and without any > customization at all. I see customization in chapter 15 - no earlier > really unless unavoidable. Great ideas here and in the outline! Before we dive into creating a new tutorial, we might want to use David O'Toole's venerable tutorial as a point of reference. Rereading it today, it's remarkable how none of the core principles of org-mode have changed despite so much development: - http://orgmode.org/worg/org-tutorials/orgtutorial_dto.php We might also take a look at the beginner's customization guide: - http://orgmode.org/worg/org-configs/org-customization-guide.php What needs to be updated there? What's missing? I do like how org currently places Bernt's and Charles's tutorials under a "power users" section, to distinguish them from basic tutorials. They are examples of how two seasoned org-mode users take advantage of the variety of features that org offers. Would it be safe to say, though, that org-mode has since grown so powerful and feature-rich that its many options can now overwhelm new users, despite its core simplicity? What I hear in Ethan's original post and in many recent mailing list posts is a request for help sorting out the essentials from the "optional" features depending on use-scenarios. An example: It seems that a new user, inspired by the many excellent tutorials on remember, might be tempted to use remember to enter *everything* in their org-files (with dozens of complex remember templates). But in many instances, it may be faster and more convenient to enter things directly into the outline. I think what we're dealing with is the paradox of choice. Too many options can paralyze/overwhelm a user. For instance, while archiving is a straightforward feature, it's easy to get hung up on the fact that there are three separate types of archiving, which gives rise to uncertainty about which to use and when to use it, or perhaps even a sense that one *must* understand and use all of them just because they all exist. With that in mind, we might add sections to the tutorial/book structured around various use scenarios: - If you're outlining/writing an book, here are some of the features that might be useful. - If you want a basic GTD system, here are a few ways you might do it. - If you want to use org for sophisticated project management and clocking, here are some of the things you might use find useful. - If you're researching a book... - If you want to keep track of interesting bookmarks on the web... - If you want to publish documents for your co-workers... Alternatively, we might move through the tutorial/dialogue feature by feature: - What in the world are drawers? Why would I want to use those? - Etc. Just a few ideas. Best, Matt