[Orgmode] Re: Documentation wishlist items

[Matt Lundin]

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. 

I'm still saying the same thing after 1 year. :)

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

I must respectfully disagree here. The org-mode basics are quite simple.
Create an outline, organize it however you see fit, mark actions as
TODOs, schedule, view and review using the agenda. To take advantage of
org, you really don't need to know much more than that. The basic
concepts would apply to any outliner or basic task management tool.

All the other features---clocking, properties, column view, exporting,
publishing, tags, tables/spreadsheets, effort estimates, etc.---are
there in the background in the event that you need them. 

Heck, even without all the extras, org would still be a world-class
outliner.

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

The manual is not your only source of information. I make heavy use of
C-h v and C-h f to learn more about particular variables and functions.

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

Here's how I see it.

1) TODO keywords: How does this item fit into my workflow?

2) Category: What group does this tree belong to? (This is the word that
   appears next to the item in the agenda.)

3) Tags: What words do I want to add to this item/tree to enable me to
   find it easily. (Commonly used for GTD contexts.)

4) Properties: What extra data would I like to attach to this item?
   (Commonly used to set special options for a subtree/item, but also
   very useful for creating ad-hoc "databases".)

In my opinion, one of the biggest decisions new users have to make is
how to designate projects. Should I use a TODO keyword, a tag, or a
second level headline? I prefer the todo keyword "PROJECT" myself, but
any of these would work fine.

And if you regret the decision three months from now, you can always use
org-map-entries to change your project items en masse.

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

My guess is that this allows him to see what group an item belongs to in
the agenda view, since categories are listed in the left column.

But this is like asking why someone puts their pots in the cupboard next
to the oven rather than above the sink, or why someone uses legal pads
rather than a spiral notebook.

My recommendation: Just start creating trees, use only a few TODO
states, and allow the organization to evolve in the way that feels the
most comfortable to you.

Best,
Matt