Re: [Orgmode] Documentation wishlist items

[Sebastian Rose]

Ethan <address@hidden> 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-mode,
> you have to understand all of the tools available, and the options you have
> 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):

=> --->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            |
   `-------------------------------------------´


  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 ->


<= ---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 =code= 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.