Re: [O] Org Tutorials need more structure

[Eric Abrahamsen]

Matt Price <address@hidden> writes:

> On Sun, Sep 29, 2013 at 4:44 AM, Eric Abrahamsen
> <address@hidden> wrote:
>> 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
>>
>> My feeling is, the tutorial structure might look like this:
>>
>> Start with the basics: outlining and structure editing, plus
>> introductions to links and properties.
>>
>> Then four other tutorials, presented in no particular order:
>>
>> 1. TODOs/agendas/task management (plus clocking)
>> 2. Exporting
>> 3. Babel
>> 4. Tables/spreadsheets
>
> I would only add that "exporting" is closely linked to "writing in
> org" whcih is what I mostly do.  This includes topics like footnotes,
> which I haven't really figured out yet after 3 years of using org
> (admittedly I haven't really tried either).

Right, but I think my point was that you can learn pretty much
everything there is to learn about authoring and note-taking in org
(including footnotes and lists and all that good stuff), without even
being aware that the export engine exists. So that can be a completely
self-contained tutorial.

Then one day someone tells you about exporting. You export your document
into six different formats, and your jaw drops. You instantly want to
start tweaking the output, and then (and only then) you read the
tutorial on exporting, which introduces you to backends, export options,
bits of literal backend code, and filters. This tutorial doesn't even
need to touch on issues of content or structure, because you've already
read about that in tutorial one, and this is /only/ about making your
documents appear differently in different output formats.

> It might also be nice if these tutorials included some sample setup
> code to get intermediate-to-advanced features working even before one
> fully understands them.

I fully agree in theory, but when you start thinking about the
complexity of custom agenda commands, or babel header lines, or TBLFM
lines... that's pretty brutal stuff.