Re: Documentation wishlist items

[Matt Lundin <mdl@imapmail.org>]

Sebastian Rose <sebastian_rose@gmx.de> writes:

> Ethan <ethan.glasser.camp@gmail.com> 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