Re: [O] Org Tutorials need more structure

[Thomas S. Dye]

Aloha Carsten,

Carsten Dominik <address@hidden> 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