Re: [Orgmode] Documentation wishlist items
Hi Ethan, Ethan ethan.glasser.c...@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 ___ 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
Re: [Orgmode] Documentation wishlist items
Sebastian Rose sebastian_r...@gmx.de writes: 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. I'm a go player. The best book I've read so far is Lessons in the fundamental of Go -- check it here: http://www.librarything.fr/work/151625 The nice thing about this book is that it's a dialog better two players, and they learn from each other. I would love to see a dialog between two org-ers, exchanging on how they progressively adapt Org to their needs or any other topics. This could actually be a bit more fun to write, and I'm sure the result would be useful. Who's in? -- Bastien ___ 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
Re: [Orgmode] Documentation wishlist items
Sebastian Rose sebastian_r...@gmx.de writes: Here is some kind of outline for such a tutorial. Wow. That an outline for a full book! And I guess that's what comes at the horizon: an (O-Reilly) book about Org-mode. It would not compete with the manual as a reference, but it would make it easier to more people to open Org's doors. -- Bastien ___ 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
Re: [Orgmode] Documentation wishlist items
On Wed, Sep 16, 2009 at 5:46 AM, Bastien bastiengue...@googlemail.comwrote: Sebastian Rose sebastian_r...@gmx.de writes: I would love to see a dialog between two org-ers, exchanging on how they progressively adapt Org to their needs or any other topics. This could actually be a bit more fun to write, and I'm sure the result would be useful. Who's in? +1 -- I'd love to see this too! ___ 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 ___ 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
Re: [Orgmode] Documentation wishlist items
Configuration through dialectic. I like it. Why not start a thread, and have an experienced user teach a newbie how to get this org-mode thing working. The only portion of the thread that would be published would be from the two users, and the rest of the list could inject comments into the thread as the users go about the business of building a config. I'll be the newbie. We are good for something after all. -Joseph Kern On Wed, Sep 16, 2009 at 5:54 AM, Greg Newman g...@20seven.org wrote: On Wed, Sep 16, 2009 at 5:46 AM, Bastien bastiengue...@googlemail.com wrote: Sebastian Rose sebastian_r...@gmx.de writes: I would love to see a dialog between two org-ers, exchanging on how they progressively adapt Org to their needs or any other topics. This could actually be a bit more fun to write, and I'm sure the result would be useful. Who's in? +1 -- I'd love to see this too! ___ 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 ___ 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 ___ 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
Re: [Orgmode] Documentation wishlist items
Am 16.09.09 11:46, schrieb Bastien: Sebastian Rosesebastian_r...@gmx.de writes: 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. I'm a go player. The best book I've read so far is Lessons in the fundamental of Go -- check it here: http://www.librarything.fr/work/151625 The nice thing about this book is that it's a dialog better two players, and they learn from each other. Another interesting source for inspiration might be the tutorials of the TikZ/PGF Manual. http://www.ctan.org/tex-archive/graphics/pgf/base/doc/generic/pgf/pgfmanual.pdf page 20 till 54 These tutorials are a nice contrast to the huge amount of reference material available in the rest of the tikz manual. Just my 2cents Regards, -- Jean-Marie ___ 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
Re: [Orgmode] Documentation wishlist items
On 16 Sep 2009, at 14:17, Jean-Marie Gaillourdet wrote: Another interesting source for inspiration might be the tutorials of the TikZ/PGF Manual. http://www.ctan.org/tex-archive/graphics/pgf/base/doc/generic/pgf/pgfmanual.pdf page 20 till 54 I agree, the tikz manual is really good. Another well done piece of documentation (and a superb program as well) is that of lilypond: http://lilypond.org/doc/v2.12/Documentation/user/lilypond-learning/index Some people have spent a *lot* of their time on that. Chapeau! I agree that org-mode could use gentler documentation, but I think that is by itself a tremendous chore. And then to keep up with all the improvements that Carsten et all produce at an almost daily rate... Cheers, Peter. ___ 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
Re: [Orgmode] Documentation wishlist items
Bastien bastiengue...@googlemail.com writes: Sebastian Rose sebastian_r...@gmx.de writes: Here is some kind of outline for such a tutorial. Wow. That an outline for a full book! And I guess that's what comes at the horizon: an (O-Reilly) book about Org-mode. It would not compete with the manual as a reference, but it would make it easier to more people to open Org's doors. OK, let's just start it. I'd like to have the tutorial on orgmode.org/worg. But I'm not yet sure about the structure. Option (A) is, to create an .../worg/the-org-tutorial/index.org, that just contains an index to the chapters. Each chapter goes to a single file in that directory. Option (B) Put the entire thing into one big file. This has the advantage, that we wouldn't need to create any extra directories on worg: orgmode.org/worg/org-tutorials/the-org-tutorial.org || (A) Multiple files | (B) Monolitic | |++---| | Outlining a skeleton | - | + | | Restructure| - | + | | Multiple editors | + | - | | Distribution (e.g. as PDF) | - | + | | Easy navigation| + | - | |++---| | Sum| -1 | +1| Thoughts? BTW: The first user in the tutorial is called Allice. I wanted to call her Trillian, but I'm afraid, people would let her add tasks, that are not easily understood :-D The readers are supposed to use their brain to understand Org-mode... Sebastian ___ 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
[Orgmode] Documentation wishlist items
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 ___ 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
Re: [Orgmode] Documentation wishlist items
Ethan ethan.glasser.c...@gmail.com 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. 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. Hmm. I think of myself as a control freak, but I never felt I'd have to understand everything in Org-mode. I don't. It works out the box, and the manual helped, in that it is a reference (not complete maybe, but complete enough). 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. Here is some kind of outline for such a tutorial. Chapter 1 It simply starts when Alice starts Emacs to take a note or jot down some ideas (brainstorming?). Headlines are moved around and later filled with text (not sure, but maybe add promotion and demotion here, too). Chapter 2 Alice adds a simple list. This would repeat the shortcuts for adding and moving headlines (they are the same, just in a similar but slightly different context. This shows for the first time in this tutorial, that all those keys are well structured). Chapter 3 Alice adds the TODO keyword to one of the headlines. I.e. she holds down the shift key while adding a headline. Chapter 5 Alice starts to work on her first TODO, and changes the TODO state to STARTED. After she finishes her work, she feels so good and switches the TODO state to DONE. (Note: We will not add any configuration options here at all. Alice just does it, and enjoys what Org-mode does for her [1]). Chapter 6 (was Chapter 4) Alice is so exited, that she adds another TODO item. But what she does now, is even more: Alice does the same/similar for plain list items: hold down the shift key, while adding an item. This is the time we introduce the `very busy C-c C-c' key as the shortcut, that updates something. Here the check boxes. Chapter 9 Alice gets tired of open the Org-file, add a note, save the buffer and close the file. She finds out about remember (or maybe Carl told her about it - or she tells Carl how to do it? Maybe Alice is an Org-pro... and Carl is one of her customers?). Again, she just uses remember as it comes with Org-mode. No special configuration necessary. That's about the speed and the first Chapters for a tutorial, I think [2]. A Page would look like this (e.g. Chapter 5): = ---8-8-8--- - previous chapter indexnext chapter - * Chapter 5: Getting things DONE Little introduction in what Alice will do in this chapter. Alice starts to work on her first TODO. Alice changes the TODO state to STARTED. More text describing how she changes the TODO state (S-RIGHT), what she does - something in Emacs maybe - is Alice an author or programmer?.. ... When finished, After she finishes her work, she feels so good and switches the TODO state to DONE. She uses the same shortcut again. Alice enjoys what Org-mode does for her. She notes the new little drawer (maybe, if this is the default) and the nice green color of the `DONE' keyword. ,---. ! Box 'WHAT WE HAVE LEARNED IN THIS CHAPTER | ! | ! S-RIGHT changes the TODO state| `---´ See also: - list of links to advanced features - for the impatient and the curious. - In the tutorial - or the Org-mode manual, worg, mailing list... - previous chapterindex next chapter - = ---8-8-8--- While this looks a little childish, it will be really relaxed reading. In the ideal case, children would be able to follow, and adults
