From mboxrd@z Thu Jan 1 00:00:00 1970 From: Sebastian Rose Subject: Re: Documentation wishlist items Date: Wed, 16 Sep 2009 05:20:30 +0200 Message-ID: <87tyz3a83l.fsf@gmx.de> References: <9cd2f5ff0909151421r25e4c7afn8d609e76e2462193@mail.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 1Mnl4Z-0002Pz-9q for emacs-orgmode@gnu.org; Tue, 15 Sep 2009 23:20:47 -0400 Received: from exim by lists.gnu.org with spam-scanned (Exim 4.43) id 1Mnl4U-0002P6-By for emacs-orgmode@gnu.org; Tue, 15 Sep 2009 23:20:46 -0400 Received: from [199.232.76.173] (port=46804 helo=monty-python.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1Mnl4U-0002P3-7s for emacs-orgmode@gnu.org; Tue, 15 Sep 2009 23:20:42 -0400 Received: from mail.gmx.net ([213.165.64.20]:35599) by monty-python.gnu.org with smtp (Exim 4.60) (envelope-from ) id 1Mnl4T-0007Zv-Jp for emacs-orgmode@gnu.org; Tue, 15 Sep 2009 23:20:42 -0400 In-Reply-To: <9cd2f5ff0909151421r25e4c7afn8d609e76e2462193@mail.gmail.com> (Ethan's message of "Tue, 15 Sep 2009 17:21:12 -0400") 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: Ethan Cc: emacs-orgmode Ethan writes: > Hi guys, > > I've been studying org-mode for a few months now, and I think I'm finally > getting the hang of it. It's really overwhelming, and I really appreciate > the efforts that must have gone into the manual and the worg project. But= I > think it still needs work. > > The fundamental problem is that org-mode isn't a planner, it isn't an > organizer. It's a toolkit full of tools which people use differently, in > lots of ways, to build their own planner/organizer. To understand org-mod= e, > you have to understand all of the tools available, and the options you ha= ve > for each, and the ways they interact with the other tools. In my opinion, > the documentation doesn't explore the interactions well enough, it doesn't > present the tools in an order that is conducive to learning, and it never > explains why you might choose one option of tool instead of another. Hmm. I think of myself as a control freak, but I never felt I'd have to understand everything in Org-mode. I don't. It works out the box, and the manual helped, in that it is a reference (not complete maybe, but complete enough). 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. Here is some kind of outline for such a tutorial. Chapter 1 It simply starts when Alice starts Emacs to take a note or jot down some ideas (brainstorming?). Headlines are moved around and later filled with text (not sure, but maybe add promotion and demotion here, too). Chapter 2 Alice adds a simple list. This would repeat the shortcuts for adding and moving headlines (they are the same, just in a similar but slightly different context. This shows for the first time in this tutorial, that all those keys are well structured). Chapter 3 Alice adds the TODO keyword to one of the headlines. I.e. she holds down the shift key while adding a headline. Chapter 5 Alice starts to work on her first TODO, and changes the TODO state to STARTED. After she finishes her work, she feels so good and switches the TODO state to DONE. (Note: We will not add any configuration options here at all. Alice just does it, and enjoys what Org-mode does for her [1]). Chapter 6 (was Chapter 4) Alice is so exited, that she adds another TODO item. But what she does now, is even more: Alice does the same/similar for plain list items: hold down the shift key, while adding an item. This is the time we introduce the `very busy C-c C-c' key as the shortcut, that updates something. Here the check boxes. Chapter 9 Alice gets tired of open the Org-file, add a note, save the buffer and close the file. She finds out about remember (or maybe Carl told her about it - or she tells Carl how to do it? Maybe Alice is an Org-pro... and Carl is one of her customers?). Again, she just uses remember as it comes with Org-mode. No special configuration necessary. .... That's about the speed and the first Chapters for a tutorial, I think [2]. A Page would look like this (e.g. Chapter 5): =3D> --->8----------------------------->8----------------------------->8--- <- previous chapter index next chapter -> * Chapter 5: Getting things DONE Little introduction in what Alice will do in this chapter. Alice starts to work on her first TODO. Alice changes the TODO state to STARTED. More text describing how she changes the TODO state (S-RIGHT), what she does - something in Emacs maybe - is Alice an author or programmer?.. ... When finished, After she finishes her work, she feels so good and switches the TODO state to DONE. She uses the same shortcut again. Alice enjoys what Org-mode does for her. She notes the new little drawer (maybe, if this is the default) and the nice green color of the `DONE' keyword. ,-------------------------------------------. ! Box 'WHAT WE HAVE LEARNED IN THIS CHAPTER | ! | ! S-RIGHT changes the TODO state | `-------------------------------------------=C2=B4 See also: - list of links to advanced features - for the impatient and the curious. - In the tutorial - or the Org-mode manual, worg, mailing list... <- previous chapter index next chapter -> <=3D ---8<-----------------------------8<-----------------------------8<--- While this looks a little childish, it will be really relaxed reading. In the ideal case, children would be able to follow, and adults wouldn't get bored. While I think about the tutorial, I see, that some of Org-mode's defaults could be reworked. Did you notice, that I did not mention emphasis, bold and fixed width in the first 9 chapters? As things stand, I would add them, when Alice starts publishing, which will be in chapter 25. I would have added it in chapter 15, if the default faces were different. I use headline faces in different font sizes and they inherit the variable face. If the default face for text would be in variable width, the fixed width face for =3Dcode=3D et al would be visible too. I don't use a variable width font for normal text, if Org-mode wouldn't use the `default' face. Best wishes Sebastian Footnotes: [1] We should discuss this in an extra thread: make log-into-drawer and clocking the default and just have it turned on (is it the default??). It's sooo useful. And I'm sure, Alice would simply enjoy it (without any customization !!!). [2] An option would be, to pack the tutorial as some kind of zip file and add some interactive features, like the Emacs tutorial has. That said, we could simply add `orgmode.org/worg/the-org-tutorial/index.org' to start it.