From mboxrd@z Thu Jan 1 00:00:00 1970 From: tsd@tsdye.com (Thomas S. Dye) Subject: Re: Org Tutorials need more structure Date: Sat, 28 Sep 2013 09:52:40 -1000 Message-ID: References: Mime-Version: 1.0 Content-Type: text/plain Return-path: Received: from eggs.gnu.org ([2001:4830:134:3::10]:48234) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1VQ0Zo-0001kY-SD for emacs-orgmode@gnu.org; Sat, 28 Sep 2013 15:53:23 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1VQ0Zi-00032l-7V for emacs-orgmode@gnu.org; Sat, 28 Sep 2013 15:53:16 -0400 Received: from oproxy13-pub.mail.unifiedlayer.com ([69.89.16.30]:58110) by eggs.gnu.org with smtp (Exim 4.71) (envelope-from ) id 1VQ0Zh-00032g-WB for emacs-orgmode@gnu.org; Sat, 28 Sep 2013 15:53:10 -0400 In-Reply-To: (Carsten Dominik's message of "Sat, 28 Sep 2013 08:11:23 +0200") List-Id: "General discussions about Org-mode." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org@gnu.org Sender: emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org@gnu.org To: Carsten Dominik Cc: emacs-orgmode list Aloha Carsten, Carsten Dominik writes: > Hi everyone, > > today I looked at our tutorial page at > > http://orgmode.org/worg/org-tutorials/index.html > > and came away with the feeling that that this page has become > somewhat useless for people who are really new to Org. I think > the page should start with a section of true recommendations > for beginners, a path we tell every new users to take in order to > learn about Org mode. > > Can we have a discussion here on how this path should look like? > When you came to Org-mode as a newby, what were the three resources > that really made an impression on by being accessible and > providing feel and promise for digging deeper? > > - Carsten Good idea! Here is my $0.02. First, I think that most statements about "what Org-mode is" are outdated. Many of them are quite good, but they represent the previous state of an evolving system and so fail to capture the full scope. To my mind, Org-mode is a "research programming interface" written by and for scientists who take very seriously certain core values of the scientific enterprise--reproducibility, open access, and open source (a partial list). Its original focus on project planning has expanded with two amazing and fundamental contributions, Eric and Dan's mature Babel implementation and Nicolas' new export framework. These core values are manifest most clearly in the Org-mode community and its organ, the mailing list. There isn't a tutorial on how to use the mailing list! I'm confident that others in the Org-mode community admire Nick Dokos' contributions to the list as much as I do. It would be great to have his perspective and approach in a short, welcoming tutorial. For me, the "philosophy" behind Org-mode shows most clearly in your talk at the Max-Planck Institute. I think this video is a must-see. On the project planning side, I think a good starting place is David O'Toole's popular tutorial. It is an efficient presentation and efficiency is one thing I think we all like about Org-mode. For me, the next step was to learn something about how to plan. I thought I knew how to do this, of course, but I really had no clue and consequently I couldn't make heads or tails of what initially struck me as a complex, ungainly set of inscrutable functions. I bought and read David Allen's little book, then followed Charles Cave's tutorial--it started to make sense! Armed with this new understanding, I found Bernt Hansen's "Organize Your Life in Plain Text" to be a huge repository of practical and useful advice (even though I have no desire to clock my unruly habits). On the research side, John Kitchin's Sci-Py talk seems to me a very good introduction. I'd follow this up with our paper in Journal of Statistical Software, which is now widely distributed. After that, I'd jump straight to John's supporting document for his paper with Alexander Hallenbeck. When this pdf document is opened in Adobe Reader (not Skim) it has links that look like push-pins. The first one of these is the Org-mode file that created the pdf document and when I double-click on it I find the Org source for his document in my Emacs. This is a terrific example of what an Org-mode file used for reproducible research should look like, very clean and disarmingly simple, a real gem. I strongly believe the Emacs newbie needs to steer clear of the temptation to lard .emacs with every tasty tidbit out there. In my experience, this is a BAD IDEA, but nearly everyone just casually says, "put this in your init file." A tutorial that gives very practical advice (some of which will undoubtedly offend or infuriate hard-core Emacs users) would be a real blessing. Finally, many of the tutorials are outdated. A good example is the one I wrote on the old LaTeX exporter. This one is clearly marked now, but it would be very good to corral the older tutorials in their own space, away from where the real tutorial action happens. Apologies for rambling. hth, Tom -- Thomas S. Dye http://www.tsdye.com