From mboxrd@z Thu Jan 1 00:00:00 1970 From: Ethan Subject: Documentation wishlist items Date: Tue, 15 Sep 2009 17:21:12 -0400 Message-ID: <9cd2f5ff0909151421r25e4c7afn8d609e76e2462193@mail.gmail.com> Mime-Version: 1.0 Content-Type: multipart/mixed; boundary="===============0336316010==" Return-path: Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.43) id 1MnfSe-0002G2-Mm for emacs-orgmode@gnu.org; Tue, 15 Sep 2009 17:21:16 -0400 Received: from exim by lists.gnu.org with spam-scanned (Exim 4.43) id 1MnfSe-0002FY-27 for emacs-orgmode@gnu.org; Tue, 15 Sep 2009 17:21:16 -0400 Received: from [199.232.76.173] (port=57979 helo=monty-python.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1MnfSd-0002FL-Lw for emacs-orgmode@gnu.org; Tue, 15 Sep 2009 17:21:15 -0400 Received: from fg-out-1718.google.com ([72.14.220.157]:19982) by monty-python.gnu.org with esmtp (Exim 4.60) (envelope-from ) id 1MnfSd-0007hi-4j for emacs-orgmode@gnu.org; Tue, 15 Sep 2009 17:21:15 -0400 Received: by fg-out-1718.google.com with SMTP id 22so1261880fge.12 for ; Tue, 15 Sep 2009 14:21:13 -0700 (PDT) List-Id: "General discussions about Org-mode." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org@gnu.org Errors-To: emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org@gnu.org To: emacs-orgmode --===============0336316010== Content-Type: multipart/alternative; boundary=00c09ffb593da496c20473a45c5f --00c09ffb593da496c20473a45c5f Content-Type: text/plain; charset=ISO-8859-1 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 --00c09ffb593da496c20473a45c5f Content-Type: text/html; charset=ISO-8859-1 Content-Transfer-Encoding: quoted-printable 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 a= nd the worg project. But I think it still needs work.

The fundamental problem is that org-mode isn't a planner, it isn= 9;t an organizer. It's a toolkit full of tools which people use differe= ntly, 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 option= s you have for each, and the ways they interact with the other tools. In my= opinion, the documentation doesn't explore the interactions well enoug= h, it doesn't present the tools in an order that is conducive to learni= ng, and it never explains why you might choose one option of tool instead o= f another.

For example, let's take Archiving. The documentation I'm readin= g 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 archivi= ng 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 mov= e 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 i= nstead 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 differenc= es are, and it's easy to confuse them with similarly-named but complete= ly distinct concepts like properties.

In other words, to really understand the manual, you have to read it tw= ice -- once to hear about all the concepts, and once more to see how they r= elate. And then to start using org-mode, you have to play with a bunch of d= ifferent possible arrangements of the concepts, see which things you like, = and finally settle on an arrangement that suits you a little bit, before st= arting 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 do= n't explain *why* they set things up in this way. For example, Bernt Ha= nsen's document explains that his toplevel headings are "main cate= gories", and shows that they each have a CATEGORY property, but doesn&= #39;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 m= ost 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 manua= l could have gone a long way in making this learning easier. For example, t= he documentation for C-u C-c C-x C-s could say something like "This su= pports workflows where there is a top-level Projects heading, and each head= ing underneath represents a project. You could then use this command to arc= hive 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 wa= nted to offer this criticism while it was still fresh in my mind.

Thanks for everything!

Ethan

--00c09ffb593da496c20473a45c5f-- --===============0336316010== Content-Type: text/plain; charset="us-ascii" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Content-Disposition: inline _______________________________________________ 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 --===============0336316010==--