all messages for Emacs-related lists mirrored at yhetil.org
 help / color / mirror / code / Atom feed
From: tsd@tsdye.com (Thomas S. Dye)
To: Carsten Dominik <carsten.dominik@gmail.com>
Cc: emacs-orgmode list <emacs-orgmode@gnu.org>
Subject: Re: Org Tutorials need more structure
Date: Sat, 28 Sep 2013 09:52:40 -1000	[thread overview]
Message-ID: <m1wqm03erb.fsf@poto.myhome.westell.com> (raw)
In-Reply-To: <EF119E90-532F-4890-991C-0C55691A898E@gmail.com> (Carsten Dominik's message of "Sat, 28 Sep 2013 08:11:23 +0200")

Aloha Carsten,

Carsten Dominik <carsten.dominik@gmail.com> 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

  parent reply	other threads:[~2013-09-28 19:53 UTC|newest]

Thread overview: 44+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2013-09-28  6:11 Org Tutorials need more structure Carsten Dominik
2013-09-28  7:22 ` Joseph Vidal-Rosset
2013-09-28  8:37   ` Marcin Borkowski
2013-09-28 10:30   ` Suvayu Ali
2013-09-28 11:59     ` Joseph Vidal-Rosset
2013-09-28 12:36       ` Eric Schulte
2013-09-28 13:10         ` Joseph Vidal-Rosset
2013-09-28 16:02       ` Suvayu Ali
2013-09-28 17:19         ` Joseph Vidal-Rosset
2013-10-01  7:59       ` Eric S Fraga
2013-10-01 20:34     ` David Rogers
2013-10-01 21:00       ` Marcin Borkowski
2013-09-28  8:48 ` Marcin Borkowski
2013-09-28 10:09   ` Carsten Dominik
2013-09-28 14:26 ` Charles Millar
2013-09-28 16:35   ` Carsten Dominik
2013-09-28 17:14 ` Ian Barton
2013-09-28 17:43   ` Marcin Borkowski
2013-09-28 17:48     ` Carsten Dominik
2013-09-28 19:06 ` Ramon Diaz-Uriarte
2013-09-28 19:52 ` Thomas S. Dye [this message]
2013-09-28 20:50   ` Charles Millar
2013-09-28 21:31     ` Marcin Borkowski
2013-09-28 21:52       ` John Hendy
2013-09-28 23:14         ` Charles Millar
2013-09-28 23:29         ` Thomas S. Dye
2013-09-29  0:29           ` John Hendy
2013-09-29  7:28             ` Suvayu Ali
2013-09-30  8:04               ` Alan Schmitt
2013-09-30 17:01                 ` Eric S Fraga
2013-09-30 18:36                   ` Peter Neilson
2013-09-30 21:07                     ` Eduardo Ochs
2013-10-01  8:52                       ` Michael Brand
2013-10-01  5:34                   ` Suvayu Ali
2013-10-01  8:55                     ` Marcin Borkowski
2013-10-01 12:40                       ` Joseph Vidal-Rosset
2013-09-30 17:56               ` Thomas S. Dye
2013-09-29  8:44 ` Eric Abrahamsen
2013-09-29 15:31   ` Matt Price
2013-09-30  7:25     ` Eric Abrahamsen
2013-10-01 14:08 ` William Denton
2013-10-02  1:10 ` M
2013-10-02 18:06   ` Alan E. Davis
  -- strict thread matches above, loose matches on Subject: below --
2013-09-29 16:43 Rustom Mody

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

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=m1wqm03erb.fsf@poto.myhome.westell.com \
    --to=tsd@tsdye.com \
    --cc=carsten.dominik@gmail.com \
    --cc=emacs-orgmode@gnu.org \
    /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 external index

	https://git.savannah.gnu.org/cgit/emacs.git
	https://git.savannah.gnu.org/cgit/emacs/org-mode.git

This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.