From: Bastien <bastienguerry@googlemail.com>
To: Ethan <ethan.glasser.camp@gmail.com>
Cc: emacs-orgmode <emacs-orgmode@gnu.org>
Subject: Re: Documentation wishlist items
Date: Wed, 16 Sep 2009 17:42:12 +0800 [thread overview]
Message-ID: <87ab0v8buz.fsf@bzg.ath.cx> (raw)
In-Reply-To: <9cd2f5ff0909151421r25e4c7afn8d609e76e2462193@mail.gmail.com> (Ethan's message of "Tue, 15 Sep 2009 17:21:12 -0400")
Hi Ethan,
Ethan <ethan.glasser.camp@gmail.com> writes:
> 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.
"needs" is the wrong word here. "might enjoy" would be better. Because
Org comes with no warranty or customer service or whatsoever :)
> 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.
The manual is a reference. It's here so that people can refer to it
when they write tutorials or when they send answers to the mailing list.
This is not to say that the manual is perfect, but as you guess, Carsten
has been incrementally working on it -- suggestions which incrementally
improve it will enjoy a warmer welcome than incentives to rewrite it...
(= patch welcome!)
On top of that, "exploring the interactions" between all Org concepts is
beyond the goals of the manual and that's why Worg exists as a community
project.
> 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.
The manual might enjoy a glossary. ;)
I have created org-glossary.org on Worg, please check it out and add
your own definitions: http://repo.or.cz/w/Worg.git
> 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.
The other way is to start using Org very spontaneously and just fetch
documentation when you feel the need of it. This is how I do and it
works well enough.
> 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
Your next contribution?
> 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.
:) I guess the other way around is also useful: share the criticism
when the fresh impression vanished, and the core of it remains.
> Thanks for everything!
Thanks for sharing your thoughts, I'm sure positive improvements will
follow.
best,
--
Bastien
next prev parent reply other threads:[~2009-09-16 9: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
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 ` Bastien [this message]
2009-09-17 3:46 ` Documentation wishlist items 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=87ab0v8buz.fsf@bzg.ath.cx \
--to=bastienguerry@googlemail.com \
--cc=emacs-orgmode@gnu.org \
--cc=ethan.glasser.camp@gmail.com \
/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).