emacs-orgmode@gnu.org archives
 help / color / mirror / code / Atom feed
From: Ethan <ethan.glasser.camp@gmail.com>
To: emacs-orgmode <emacs-orgmode@gnu.org>
Subject: Documentation wishlist items
Date: Tue, 15 Sep 2009 17:21:12 -0400	[thread overview]
Message-ID: <9cd2f5ff0909151421r25e4c7afn8d609e76e2462193@mail.gmail.com> (raw)


[-- Attachment #1.1: Type: text/plain, Size: 3487 bytes --]

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.

For example, let's take Archiving. The documentation I'm reading right now,
at http://orgmode.org/manual/Archiving.html#Archiving, puts archiving in
"Document Structure", section 2.6, before TODO keywords, tags, the agenda,
or anything else. There's one paragraph about what archiving means, then
five or six paragraphs about how a headline with the ARCHIVE tag behaves,
and then a section about moving trees and where you could move them. It
isn't clear what workflows you might use Archive Sibling in, or why C-u C-c
C-x C-s would archive *children* of the selected headline instead of the
headline itself.

Another good example is TODO keywords, categories, and tags. It isn't clear
what they all are, or why they are distinct, or what the differences are,
and it's easy to confuse them with similarly-named but completely distinct
concepts like properties.

In other words, to really understand the manual, you have to read it twice
-- once to hear about all the concepts, and once more to see how they
relate. And then to start using org-mode, you have to play with a bunch of
different possible arrangements of the concepts, see which things you like,
and finally settle on an arrangement that suits you a little bit, before
starting the endless path of tweakage.

Reading HOWTO's like Bernt Hansen's and Charles Cave's are really
interesting to see how people work, but even documents like these don't
explain *why* they set things up in this way. For example, Bernt Hansen's
document explains that his toplevel headings are "main categories", and
shows that they each have a CATEGORY property, but doesn't explain what that
buys him, or what problem that solves.

In short, after studying org-mode for a long time, I finally feel ready to
start using it -- not that I understand it, but that I know where the most
important knobs are. I feel like it would have been a lot easier for me to
start using it if I had started with a tutorial that explained a single
workflow and how org-mode supported it, and I feel like the org-mode manual
could have gone a long way in making this learning easier. For example, the
documentation for C-u C-c C-x C-s could say something like "This supports
workflows where there is a top-level Projects heading, and each heading
underneath represents a project. You could then use this command to archive
all projects which didn't have open TODO items.".

I wish I could offer more concrete improvements in the form of patches and
so on! Maybe as I learn more about org-mode I can do this too, but I wanted
to offer this criticism while it was still fresh in my mind.

Thanks for everything!

Ethan

[-- Attachment #1.2: Type: text/html, Size: 3751 bytes --]

[-- Attachment #2: Type: text/plain, Size: 204 bytes --]

_______________________________________________
Emacs-orgmode mailing list
Remember: use `Reply All' to send replies to the list.
Emacs-orgmode@gnu.org
http://lists.gnu.org/mailman/listinfo/emacs-orgmode

             reply	other threads:[~2009-09-15 21:21 UTC|newest]

Thread overview: 26+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2009-09-15 21:21 Ethan [this message]
2009-09-15 23:56 ` Documentation wishlist items 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
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=9cd2f5ff0909151421r25e4c7afn8d609e76e2462193@mail.gmail.com \
    --to=ethan.glasser.camp@gmail.com \
    --cc=emacs-orgmode@gnu.org \
    /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).