From: Matt Lundin <mdl@imapmail.org>
To: Sebastian Rose <sebastian_rose@gmx.de>
Cc: emacs-orgmode <emacs-orgmode@gnu.org>
Subject: Re: Documentation wishlist items
Date: Wed, 16 Sep 2009 08:46:57 -0400 [thread overview]
Message-ID: <874or3njjy.fsf@fastmail.fm> (raw)
In-Reply-To: <87tyz3a83l.fsf@gmx.de> (Sebastian Rose's message of "Wed, 16 Sep 2009 05:20:30 +0200")
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
next prev parent reply other threads:[~2009-09-16 12:42 UTC|newest]
Thread overview: 26+ messages / expand[flat|nested] mbox.gz Atom feed top
2009-09-15 21:21 Documentation wishlist items Ethan
2009-09-15 23:56 ` Sean Sieger
2009-09-16 3:20 ` Sebastian Rose
2009-09-16 9:46 ` Bastien
2009-09-16 9:54 ` Greg Newman
2009-09-16 10:04 ` timetrap
2009-09-16 12:17 ` Jean-Marie Gaillourdet
2009-09-16 12:56 ` Peter Frings
2009-09-16 9:49 ` Bastien
2009-09-16 14:10 ` Sebastian Rose
2009-09-16 16:03 ` Matt Lundin
2009-09-16 12:46 ` Matt Lundin [this message]
2009-09-16 3:34 ` Matt Lundin
2009-09-16 11:37 ` Bernt Hansen
2009-09-16 15:33 ` Ethan
2009-09-16 16:32 ` Matthew Lundin
2009-09-16 18:42 ` tycho garen
2009-09-18 15:02 ` org-invoice question Dave Täht
2009-09-21 17:15 ` Peter Jones
2009-09-21 17:30 ` Dave Täht
2009-09-18 15:19 ` org-examples.git? Dave Täht
2009-09-18 17:00 ` org-examples.git? Matt Lundin
2009-09-16 9:42 ` Documentation wishlist items Bastien
2009-09-17 3:46 ` Matt Lundin
2009-09-17 17:34 ` Ethan
2009-09-17 19:30 ` Matthew Lundin
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: https://www.orgmode.org/
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=874or3njjy.fsf@fastmail.fm \
--to=mdl@imapmail.org \
--cc=emacs-orgmode@gnu.org \
--cc=sebastian_rose@gmx.de \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).