Org Tutorials need more structure

Org Tutorials need more structure

[Carsten Dominik]

[-- Attachment #1: Type: text/plain, Size: 629 bytes --]

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

[-- Attachment #2: Message signed with OpenPGP using GPGMail --]
[-- Type: application/pgp-signature, Size: 455 bytes --]

Re: Org Tutorials need more structure

[Joseph Vidal-Rosset]

[-- Attachment #1: Type: text/plain, Size: 2411 bytes --]

Hi Dominik, hi everyone,

Thank you for org-mode and thanks to all who contribute to this project.

I am a newby to org-mode , I am an emacs user for LaTeX, mainly, and I
would be happy to use more and more emacs, so org-mode seems very
attractive.

I imagine that writing a tutorial is a big work and I hope that I will not
offend people who have taken this time. But I must say that the org-mode
manual and the tutorials that I have tried to read are not enough
progressive for beginners and do not take care of difference between
interests of people.

Example: I am presently mainly interested to see if it is possible to use
gnus to write a scientific letter with all conveniences of texlive. Of
course I can open a tex file with letter class and send to my colleague a
pdf file. But it would be more convenient to write an email and using
conversions to html and png images to send to him directly this email. I
guess it is possilbe to do it with gnus. But the documentation is esoteric:
I hear about links, but how it works concretly with example understanble by
a newby ...  mystery. It is therefore frustrating and quickly discouraging.

So, in my opinion, a good tutorial is divided into precise tasks and speaks
like that:
"You need to do that?  So, follow me , from step to step, I will going to
show you how I succeed to do what you want to do, and by imitation, you
will also succeed ! "  A good tutorial avoids to suppose that the reader is
already an expert.

In a word, too much tutorial in org-mode lack of pedagogical efforts.

Sorry to be speak so frankly, but I hope it will help.

Waiting your help with gnus - latex and conversion in html , etc. etc.

All the best

Jo.


2013/9/28 Carsten Dominik <carsten.dominik@gmail.com>

> 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
>

[-- Attachment #2: Type: text/html, Size: 3220 bytes --]

Re: Org Tutorials need more structure

[Marcin Borkowski]

Dnia 2013-09-28, o godz. 09:22:02
Joseph Vidal-Rosset <joseph.vidal.rosset@gmail.com> napisał(a):

> Hi Dominik, hi everyone,
> 
> Thank you for org-mode and thanks to all who contribute to this
> project.
> 
> I am a newby to org-mode , I am an emacs user for LaTeX, mainly, and I
> would be happy to use more and more emacs, so org-mode seems very
> attractive.
> 
> I imagine that writing a tutorial is a big work and I hope that I
> will not offend people who have taken this time. But I must say that
> the org-mode manual and the tutorials that I have tried to read are
> not enough progressive for beginners and do not take care of
> difference between interests of people.
> 
> Example: I am presently mainly interested to see if it is possible to
> use gnus to write a scientific letter with all conveniences of
> texlive. Of course I can open a tex file with letter class and send
> to my colleague a pdf file. But it would be more convenient to write
> an email and using conversions to html and png images to send to him
> directly this email. I guess it is possilbe to do it with gnus. But
> the documentation is esoteric: I hear about links, but how it works
> concretly with example understanble by a newby ...  mystery. It is
> therefore frustrating and quickly discouraging.
> 
> So, in my opinion, a good tutorial is divided into precise tasks and
> speaks like that:
> "You need to do that?  So, follow me , from step to step, I will
> going to show you how I succeed to do what you want to do, and by
> imitation, you will also succeed ! "  A good tutorial avoids to
> suppose that the reader is already an expert.
> 
> In a word, too much tutorial in org-mode lack of pedagogical efforts.
> 
> Sorry to be speak so frankly, but I hope it will help.
> 
> Waiting your help with gnus - latex and conversion in html , etc. etc.
> 
> All the best
> 
> Jo.

Well, from what I heard, Gnus is a bad example - it seems to be
notoriously difficult to get into.  OTOH, with Org-mode it is much
better - I found even the manual *very* accessible, at least for a
long-time Emacs user.

Best,

-- 
Marcin Borkowski
http://octd.wmi.amu.edu.pl/en/Marcin_Borkowski
Adam Mickiewicz University

Re: Org Tutorials need more structure

[Marcin Borkowski]

Dnia 2013-09-28, o godz. 08:11:23
Carsten Dominik <carsten.dominik@gmail.com> napisał(a):

> 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?

As I hinted in my previous email, there are two cases:

1. Emacs users who are new to Org-mode.

This is basically covered by the manual.  Period.

2. People new to Emacs who might want to use it /because/ of Org-mode.

Here we have a huge potential for improvement, so to speak;).

A couple of thoughts:

- Screencasts and videos might be a viable option (even though it is a
  bit old, I consider your Google lecture a very good introduction to
  Org-mode - a survey of features; it is, however, aimed more at a
  power user than a newbie).
- What might be really interesting would be something along the lines
  of C-h t.  In fact, the Emacs tutorial itself badly needs an update
  imho.  And a similar thing for Org-mode might be even better.  In
  fact, though I am quite busy at the moment, I'd be happy to start
  thinking about something like this in my free time.  What do you
  think?
- For new users, there might be an installation instruction /including/
  installing Emacs (especially on Windows machines, where it might be
  tricky).  I think it should be emphasized that (at least in case of
  Org-mode) Emacs may be treated more as an application framework,
  which incidentally has more text-editing capabilities than, say, edit
  boxes of GTK etc. (just a bit more, you know;)), and that Org-mode is
  an application running in this particular environment.  (Calling it an
  Elisp Virtual Machine might be a bit stretching, though;).)
- Last but not least: we are still waiting for Sacha Chua to draw a
  sketchnote-based intro to Org-mode;).

> - Carsten

Best,

-- 
Marcin Borkowski
http://octd.wmi.amu.edu.pl/en/Marcin_Borkowski
Adam Mickiewicz University

Re: Org Tutorials need more structure

[Carsten Dominik]

[-- Attachment #1: Type: text/plain, Size: 3353 bytes --]


On 28.9.2013, at 10:48, Marcin Borkowski <mbork@wmi.amu.edu.pl> wrote:

> Dnia 2013-09-28, o godz. 08:11:23
> Carsten Dominik <carsten.dominik@gmail.com> napisał(a):
> 
>> 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?
> 
> As I hinted in my previous email, there are two cases:
> 
> 1. Emacs users who are new to Org-mode.
> 
> This is basically covered by the manual.  Period.
> 
> 2. People new to Emacs who might want to use it /because/ of Org-mode.
> 
> Here we have a huge potential for improvement, so to speak;).
> 
> A couple of thoughts:
> 
> - Screencasts and videos might be a viable option (even though it is a
>  bit old, I consider your Google lecture a very good introduction to
>  Org-mode - a survey of features; it is, however, aimed more at a
>  power user than a newbie).
> - What might be really interesting would be something along the lines
>  of C-h t.  In fact, the Emacs tutorial itself badly needs an update
>  imho.  And a similar thing for Org-mode might be even better.  In
>  fact, though I am quite busy at the moment, I'd be happy to start
>  thinking about something like this in my free time.  What do you
>  think?
> - For new users, there might be an installation instruction /including/
>  installing Emacs (especially on Windows machines, where it might be
>  tricky).  I think it should be emphasized that (at least in case of
>  Org-mode) Emacs may be treated more as an application framework,
>  which incidentally has more text-editing capabilities than, say, edit
>  boxes of GTK etc. (just a bit more, you know;)), and that Org-mode is
>  an application running in this particular environment.  (Calling it an
>  Elisp Virtual Machine might be a bit stretching, though;).)
> - Last but not least: we are still waiting for Sacha Chua to draw a
>  sketchnote-based intro to Org-mode;).

Hi Marcin,

thanks for your input!

However, for now, O was not asking for new material to be
produced (even though that may be interesting as well),
but rather I wanted to make a selection of the large
numbers of talks, screencasts, tutorials that introduce
into Org more progressively.  For example, my talk at
Google is too long as the first thing a newbie should
encounter.  I was hoping we can identify maybe 5 different
things (screencasts, tutorials, whatever) that we advertise
at the top of the tutorial page as the recommended default
introduction into Org.  The rest of the tutorial page is then
still there as additional reference for people who stay and want
to dig deeper.  The problem I have with the tutorial page
right now is that there is a huge amount of tutorials,
and no guidance for beginners.

- Carsten

[-- Attachment #2: Message signed with OpenPGP using GPGMail --]
[-- Type: application/pgp-signature, Size: 455 bytes --]

Re: Org Tutorials need more structure

[Suvayu Ali]

Hi Joseph,

On Sat, Sep 28, 2013 at 09:22:02AM +0200, Joseph Vidal-Rosset wrote:
> 
> Example: I am presently mainly interested to see if it is possible to use
> gnus to write a scientific letter with all conveniences of texlive. Of
> course I can open a tex file with letter class and send to my colleague a
> pdf file. But it would be more convenient to write an email and using
> conversions to html and png images to send to him directly this email. I
> guess it is possilbe to do it with gnus. But the documentation is esoteric:
> I hear about links, but how it works concretly with example understanble by
> a newby ...  mystery. It is therefore frustrating and quickly discouraging.

Your example is not beginner's tutorial at all!  Nor is it something
that the manual can cover.  For esoteric/specific needs like this
"advanced tutorials" are more appropriate.

Now to answer your question, I have seen people mention htmlize.el from
contrib for something like this.  To integrate with LaTeX, you should be
able work out a solution with some dvipng magic.  If memory serves me
right, there was a post from Eric[1] mentioning how to use htmlize from
gnus, and a thread on dvipng in the last month.  Those might help you.

As for Carsten's suggestion.  I agree completely.  It's a jungle of
tutorials, I myself get confused on that page.  I'll try to come-up with
a shortlist of beginner tutorials in a few days.

Cheers,


Footnotes:

[1] okay, found it: <http://mid.gmane.org/87ppsba2tc.fsf@ucl.ac.uk>


-- 
Suvayu

Open source is the future. It sets us free.

Re: Org Tutorials need more structure

[Joseph Vidal-Rosset]

[-- Attachment #1: Type: text/plain, Size: 1653 bytes --]

Hi,

2013/9/28 Suvayu Ali <fatkasuvayu+linux@gmail.com>

> Your example is not beginner's tutorial at all!  Nor is it something
> that the manual can cover.
>

I do not understand why. Every beginner intested in org-mode is interested
for such or such application, and that's a strange reply to make to a
beginner like me to reply : "sorry but your request is not a beginner's
request". And if I am interested in org-mode mainly for the feature?



>  For esoteric/specific needs like this
> "advanced tutorials" are more appropriate.
>

I have not found a clear tutorial to help me on this point, and even in the
org-mode manual, the relationship between org-mode and emacs email client
like gnus is very difficult to understand. Again, I have not seen an easy
example to follow.


>
> Now to answer your question, I have seen people mention htmlize.el from
> contrib for something like this.  To integrate with LaTeX, you should be
> able work out a solution with some dvipng magic.  If memory serves me
> right, there was a post from Eric[1] mentioning how to use htmlize from
> gnus, and a thread on dvipng in the last month.  Those might help you.
>

Thanks for this reference, I have tried these commands on a draft in my
gnus, of course nothing work. I suspect that I need to configure gnus
before...

My point in this discussion was to pointing out that it is not only
structure of tutorials  can be a problem, but the content of explanations.
Again, if no example is given for each task that one can realize with
org-mode, only geeks expert in emacs will be able to read manuals for
org-mode, and in my opinion it's too bad.

Best wishes,

Jo.

[-- Attachment #2: Type: text/html, Size: 2596 bytes --]

Re: Org Tutorials need more structure

[Eric Schulte]

Joseph Vidal-Rosset <joseph.vidal.rosset@gmail.com> writes:

> Hi,
>
> 2013/9/28 Suvayu Ali <fatkasuvayu+linux@gmail.com>
>
>> Your example is not beginner's tutorial at all!  Nor is it something
>> that the manual can cover.
>>
>
> I do not understand why. Every beginner intested in org-mode is interested
> for such or such application, and that's a strange reply to make to a
> beginner like me to reply : "sorry but your request is not a beginner's
> request". And if I am interested in org-mode mainly for the feature?
>
>

Org-mode is an application for the following (from the manual).

> Org is a mode for keeping notes, maintaining TODO lists, and doing
> project planning with a fast and effective plain-text system.

Email is not mentioned in this description and is not core to what
Org-mode does.  I think the point made in the previous email is that
your use case is neither basic nor typical Org-mode usage.

>
> I have not found a clear tutorial to help me on this point, and even in the
> org-mode manual, the relationship between org-mode and emacs email client
> like gnus is very difficult to understand. Again, I have not seen an easy
> example to follow.
>

The feature (sending email with embedded equations compiled from latex)
is provided by org-mime, which is a contributed package build on top of
Org-mode.  It is not mentioned in the Org-mode manual because it is
*not* part of Org-mode, it is built on top of Org-mode.

See [1] for a tutorial on using org-mime.  Sometimes when using a tool
like Org-mime which leverages other tools (e.g., message-mode and
org-mode) it is necessary to learn all of the sub-tools at once which
can result in a great deal of reading, there's no way to avoid this.

>
>
>>
>> Now to answer your question, I have seen people mention htmlize.el from
>> contrib for something like this.  To integrate with LaTeX, you should be
>> able work out a solution with some dvipng magic.  If memory serves me
>> right, there was a post from Eric[1] mentioning how to use htmlize from
>> gnus, and a thread on dvipng in the last month.  Those might help you.
>>
>
> Thanks for this reference, I have tried these commands on a draft in my
> gnus, of course nothing work. I suspect that I need to configure gnus
> before...
>

I doubt this is related to your gnus configuration.  Please try the
tutorial linked below, and if you run into a problem then provide a
complete reproducible recipe for what you've tried and how it failed and
maybe we can help you to use these packages.

>
> My point in this discussion was to pointing out that it is not only
> structure of tutorials  can be a problem, but the content of explanations.
> Again, if no example is given for each task that one can realize with
> org-mode, only geeks expert in emacs will be able to read manuals for
> org-mode, and in my opinion it's too bad.
>

There is a need to balance between spending time spent documenting and
spending time developing (fixing bugs and adding features etc...).  More
documentation and more examples in the documentation would be welcome,
but given the time constraints of Org-mode developers and contributors
not every desirable task can be accomplished.

Cheers,

>
> Best wishes,
>
> Jo.


Footnotes: 
[1]  http://orgmode.org/worg/org-contrib/org-mime.html

-- 
Eric Schulte
https://cs.unm.edu/~eschulte
PGP: 0x614CA05D

Re: Org Tutorials need more structure

[Joseph Vidal-Rosset]

[-- Attachment #1: Type: text/plain, Size: 865 bytes --]

2013/9/28 Eric Schulte <schulte.eric@gmail.com>

> There is a need to balance between spending time spent documenting and
> spending time developing (fixing bugs and adding features etc...).  More
> documentation and more examples in the documentation would be welcome,
> but given the time constraints of Org-mode developers and contributors
> not every desirable task can be accomplished.
>

Thanks Eric for these explanations. Again my remark is not to be understood
as an harsh critic. Just a remark on a gap existing in every educational
task: sometimes teachers do not understand why students do not understand.
What seems very easy to some people is obscure for others who need more
time and more explanations.

I am going to read your tutorial, and I thank you warmly for your help. Of
course I will tell you if I succeed or if I do not.

All the best

Jo.

[-- Attachment #2: Type: text/html, Size: 1425 bytes --]

Re: Org Tutorials need more structure

[Charles Millar]

[-- Attachment #1: Type: text/plain, Size: 1449 bytes --]

Hi Carsten,

On 9/28/2013 2:11 AM, Carsten Dominik wrote:
> 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 disagree. Your Google talk was just right - for me. It was my first 
exposure to 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?
About three years ago I stumbled across Org Mode when I was searching 
Emacs in general. (I already was familiar with Emacs, but only to "fool 
around".)
After viewing the Google talk, I specifically searched Org Mode. The 
three resources that made an impression:
- the general tutorials, starting with David O'Toole's,
- the Compact Guide with the Further Readings, (I did not look at the 
ones in the Org Manual) since this gave me a sense of how Org is and can 
be used, and
- *the mailing list*, which was the one resource that has made the 
greatest impression on me from the beginning. It has been and is my best 
resource; it provides the greatest exposure to Org Mode both as to its 
uses and sense of the Org community.
- Thank you Carsten, Bastien and all the rest if you for Org Mode.

Charlie Millar


[-- Attachment #2: Type: text/html, Size: 2153 bytes --]

Re: Org Tutorials need more structure

[Suvayu Ali]

Hi Joseph,

On Sat, Sep 28, 2013 at 01:59:28PM +0200, Joseph Vidal-Rosset wrote:
> Hi,
> 
> 2013/9/28 Suvayu Ali <fatkasuvayu+linux@gmail.com>
> 
> > Your example is not beginner's tutorial at all!  Nor is it something
> > that the manual can cover.
> >
> 
> I do not understand why. Every beginner intested in org-mode is interested
> for such or such application, and that's a strange reply to make to a
> beginner like me to reply : "sorry but your request is not a beginner's
> request". And if I am interested in org-mode mainly for the feature?

I'm sorry my response came off that way.  All that I wanted to say was:
you are trying to leverage Org into doing something that it was not
designed to do.  That is not a bad thing at all.  The community always
welcomes such creative efforts and always makes an effort to document it
(usually on Worg).  Partly, this is also the reason why navigating
through the information available on Worg can be daunting.  I believe
Eric echoed the same sentiment in another message.

> >  For esoteric/specific needs like this
> > "advanced tutorials" are more appropriate.
> >
> 
> I have not found a clear tutorial to help me on this point, and even in the
> org-mode manual, the relationship between org-mode and emacs email client
> like gnus is very difficult to understand. Again, I have not seen an easy
> example to follow.

This actually proves my point.  Tutorials are written by volunteers like
you and me.  If there is no tutorial, it means no one has encoutered the
problem or encoutered and solved it (at least did not put effort into
documenting it).  In such a case please feel free to ask on the mailing
list.  Tell us what you want to achieve, what you have tried, and
someone with a bright idea will chime in.  I'm sure you have noticed it
by now, the Org community is one of the most welcoming and friendly out
there.

Good luck following up on Eric's suggestions with regards to your
particular request.  If you do get it working, I would encourage you to
document it on Worg or the mailing list.

Cheers,

-- 
Suvayu

Open source is the future. It sets us free.

Re: Org Tutorials need more structure

[Carsten Dominik]

[-- Attachment #1: Type: text/plain, Size: 1725 bytes --]


On 28.9.2013, at 16:26, Charles Millar <millarc@verizon.net> wrote:

> Hi Carsten,
> 
> On 9/28/2013 2:11 AM, Carsten Dominik wrote:
>> 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 disagree. Your Google talk was just right - for me. It was my first exposure to Org Mode.

Well, I am glad to hear that it still does its work.

>> 
>> 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?
>> 
> About three years ago I stumbled across Org Mode when I was searching Emacs in general. (I already was familiar with Emacs, but only to "fool around".)
> After viewing the Google talk, I specifically searched Org Mode. The three resources that made an impression:
> - the general tutorials, starting with David O'Toole's, 
> - the Compact Guide with the Further Readings, (I did not look at the ones in the Org Manual) since this gave me a sense of how Org is and can be used, and
> - the mailing list, which was the one resource that has made the greatest impression on me from the beginning. It has been and is my best resource; it provides the greatest exposure to Org Mode both as to its uses and sense of the Org community.

Thank you for your input to this discussion.

- Carsten

> - Thank you Carsten, Bastien and all the rest if you for Org Mode.
> 
> Charlie Millar
> 


[-- Attachment #2: Message signed with OpenPGP using GPGMail --]
[-- Type: application/pgp-signature, Size: 455 bytes --]

Re: Org Tutorials need more structure

[Ian Barton]

On 28/09/13 07:11, Carsten Dominik wrote:

>
> 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
>

I think we need to try and identify why most new users come to org-mode. 
This might give a better idea of how to re-organize things.

I am guessing that initially many users are attracted by the task 
management and outlining features. From these basic features flow things 
such as publishing, clocking, Babel. So maybe listing Tutorials in this 
order would be a start.

Personally if I am learning something new I want a broad overview of the 
main features, with links to places where I can find more detail.

For example  David O'Toole's and Sacha's tutorials cover this very well. 
The videos are an excellent resource, but require the user to set aside 
30-60mins in one block of time. People are more likely to watch them if 
their initial interest has been piqued by something they can read and 
digest in small blocks.

Ian.

Re: Org Tutorials need more structure

[Joseph Vidal-Rosset]

[-- Attachment #1: Type: text/plain, Size: 542 bytes --]

2013/9/28 Suvayu Ali <fatkasuvayu+linux@gmail.com>

>  I'm sure you have noticed it
> by now, the Org community is one of the most welcoming and friendly out
> there.
>

Indeed it is !


>
> Good luck following up on Eric's suggestions with regards to your
> particular request.  If you do get it working, I would encourage you to
> document it on Worg or the mailing list.
>

Many thanks for your email. I am going to read and to apply Eric
documentation. I wlll tell you the result and I hope that it will be useful
too.

All the best

Jo.

[-- Attachment #2: Type: text/html, Size: 1199 bytes --]

Re: Org Tutorials need more structure

[Marcin Borkowski]

Dnia 2013-09-28, o godz. 18:14:11
Ian Barton <lists@wilkesley.net> napisał(a):

> On 28/09/13 07:11, Carsten Dominik wrote:
> 
> >
> > 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
> >
> 
> I think we need to try and identify why most new users come to
> org-mode. This might give a better idea of how to re-organize things.
> 
> I am guessing that initially many users are attracted by the task 
> management and outlining features. From these basic features flow
> things such as publishing, clocking, Babel. So maybe listing
> Tutorials in this order would be a start.
> 
> Personally if I am learning something new I want a broad overview of
> the main features, with links to places where I can find more detail.
> 
> For example  David O'Toole's and Sacha's tutorials cover this very
> well. The videos are an excellent resource, but require the user to
> set aside 30-60mins in one block of time. People are more likely to
> watch them if their initial interest has been piqued by something
> they can read and digest in small blocks.

Hear, hear.

What I would love to see is a 4-5 minutes video "trailer", showing most
prominent features of Org-mode, with cool music, effects etc. - like
movie trailers.

:)

> 
> Ian.
> 
> 

Best,

-- 
Marcin Borkowski
http://octd.wmi.amu.edu.pl/en/Marcin_Borkowski
Adam Mickiewicz University

Re: Org Tutorials need more structure

[Carsten Dominik]

[-- Attachment #1: Type: text/plain, Size: 1864 bytes --]


On 28.9.2013, at 19:43, Marcin Borkowski <mbork@wmi.amu.edu.pl> wrote:

> Dnia 2013-09-28, o godz. 18:14:11
> Ian Barton <lists@wilkesley.net> napisał(a):
> 
>> On 28/09/13 07:11, Carsten Dominik wrote:
>> 
>>> 
>>> 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
>>> 
>> 
>> I think we need to try and identify why most new users come to
>> org-mode. This might give a better idea of how to re-organize things.
>> 
>> I am guessing that initially many users are attracted by the task 
>> management and outlining features. From these basic features flow
>> things such as publishing, clocking, Babel. So maybe listing
>> Tutorials in this order would be a start.
>> 
>> Personally if I am learning something new I want a broad overview of
>> the main features, with links to places where I can find more detail.
>> 
>> For example  David O'Toole's and Sacha's tutorials cover this very
>> well. The videos are an excellent resource, but require the user to
>> set aside 30-60mins in one block of time. People are more likely to
>> watch them if their initial interest has been piqued by something
>> they can read and digest in small blocks.
> 
> Hear, hear.
> 
> What I would love to see is a 4-5 minutes video "trailer", showing most
> prominent features of Org-mode, with cool music, effects etc. - like
> movie trailers.
> 
> :)

Yes, I'd love that too.  High quality, show effects but don't explain key bindings.

:)

- Carsten

> 
>> 
>> Ian.
>> 
>> 
> 
> Best,
> 
> -- 
> Marcin Borkowski
> http://octd.wmi.amu.edu.pl/en/Marcin_Borkowski
> Adam Mickiewicz University
> 


[-- Attachment #2: Message signed with OpenPGP using GPGMail --]
[-- Type: application/pgp-signature, Size: 455 bytes --]

Re: Org Tutorials need more structure

[Ramon Diaz-Uriarte]

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?

Dear Carsten,


For me it was one resource: the compact guide. I found it well written, with
links to additional info if I needed it, and structured in such a way that I
could really start using immediately what I was most interested in at the moment
(initially outlines and scheduling). [Some context: I came to org looking for
the outlines and scheduling, and a vague desire for literate programming,
because I wanted these features fully within Emacs, after having played with Leo
---http://leoeditor.com/--- for around a year].



To see what I might feel today, I just went to the first hit I get in google for
org mode (which is, of course, http://orgmode.org/) and still find the compact
guide. But maybe it would be good to emphasize it a bit more (there are ten
lines of text, and the compact guide is the fifth). As well, a link to the
compact guide might be added from the org-tutorial page.



Finally, regarding the org-tutorial page, as it has already been mentioned in
this thread, videos might not be the best vehicle for everyone (certainly not
for me ---I'd rather read text where I can adjust the pace to that of my
brain). Sacha's "Outlining your notes with org" made a lasting impression,
though (but Sacha's blog entry was written after I read the compact guide,
IIRC).


Best (and thanks for org),


R.




>
> - Carsten


-- 
Ramon Diaz-Uriarte
Department of Biochemistry, Lab B-25
Facultad de Medicina 
Universidad Autónoma de Madrid 
Arzobispo Morcillo, 4
28029 Madrid
Spain

Phone: +34-91-497-2412

Email: rdiaz02@gmail.com
       ramon.diaz@iib.uam.es

http://ligarto.org/rdiaz

Re: Org Tutorials need more structure

[Thomas S. Dye]

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

Re: Org Tutorials need more structure

[Charles Millar]

On 9/28/2013 3:52 PM, Thomas S. Dye wrote:
> Aloha Carsten,
>
snip
> 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).
Strongly disagree with the sentiment. My undergraduate degree may gave 
been Physics, but I work as a freelance paralegal. I use Org Mode for 
project (file) planning, scheduling, drafting documents, etc. Also, I 
believe that there are some very active participants on this list who 
are not scientists and have made great contributions.
> 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.
I use the LaTeX export to create pdf documents, such as contracts and 
pleadings, nothing "scientific" there. Sometimes I will export to utf-8 
text file, so I can copy and paste into "those other" document formats. 
(Sorry to say, but most of the US legal community is still MS Word and 
WordPerfect oriented.) I believe that I can eventually use Org-Babel for 
reproducible "research", research being more other than scientific.
>
> 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.
No argument about the mailing list - see my earlier post. Also, Nick has 
helped me a few times; and I might add, I make sure that I read your 
posts - this is not to curry favor!
> hth,
> Tom
>

Charlie Millar

Re: Org Tutorials need more structure

[Marcin Borkowski]

Dnia 2013-09-28, o godz. 16:50:09
Charles Millar <millarc@verizon.net> napisał(a):

> On 9/28/2013 3:52 PM, Thomas S. Dye wrote:
> > Aloha Carsten,
> >
> snip
> > 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).
> Strongly disagree with the sentiment. My undergraduate degree may
> gave been Physics, but I work as a freelance paralegal. I use Org
> Mode for project (file) planning, scheduling, drafting documents,
> etc. Also, I believe that there are some very active participants on
> this list who are not scientists and have made great contributions.

+1.  Although I'm also a scientist (mathematics), I used Org-mode /once/
for science, and it turned out that I felt very much constrained and
quickly got back to LaTeX, where I felt much more comfortable.

> > 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.
> I use the LaTeX export to create pdf documents, such as contracts and 
> pleadings, nothing "scientific" there. Sometimes I will export to
> utf-8 text file, so I can copy and paste into "those other" document
> formats. (Sorry to say, but most of the US legal community is still
> MS Word and WordPerfect oriented.) I believe that I can eventually
> use Org-Babel for reproducible "research", research being more other
> than scientific.

For me, Org-mode is /mainly/ a planner, outliner, scheduler, clocking
device and a tool to write blog posts.  I use Org spreadsheets just a
little bit.  As I mentioned, I work heavily with LaTeX (and beamer), but
do not use Org-mode for that (maybe apart from the initial stage) -- I
am comfortable with LaTeX (using AUCTeX, of course), so Org-mode export
does nothing for me.

This seems to confirm that Org is quite flexible and can be adapted to
a variety of workflows.

Best,

-- 
Marcin Borkowski
http://octd.wmi.amu.edu.pl/en/Marcin_Borkowski
Adam Mickiewicz University

Re: Org Tutorials need more structure

[John Hendy]

On Sat, Sep 28, 2013 at 4:31 PM, Marcin Borkowski <mbork@wmi.amu.edu.pl> wrote:
> Dnia 2013-09-28, o godz. 16:50:09
> Charles Millar <millarc@verizon.net> napisał(a):
>
>> On 9/28/2013 3:52 PM, Thomas S. Dye wrote:
>> > Aloha Carsten,
>> >
>> snip
>> > 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).
>> Strongly disagree with the sentiment. My undergraduate degree may
>> gave been Physics, but I work as a freelance paralegal. I use Org
>> Mode for project (file) planning, scheduling, drafting documents,
>> etc. Also, I believe that there are some very active participants on
>> this list who are not scientists and have made great contributions.
>
> +1.  Although I'm also a scientist (mathematics), I used Org-mode /once/
> for science, and it turned out that I felt very much constrained and
> quickly got back to LaTeX, where I felt much more comfortable.
> http://octd.wmi.amu.edu.pl/en/Marcin_Borkowski
> Adam Mickiewicz University
>

This is starting to remind me of bike-shedding. Org-mode is a toolbox
providing various things that can work toward whatever end one wants.
It's agnostic to field. It doesn't really matter what the end uses are
-- Org-mode "is" what functions it provides. How those are combined by
others in various fields, lines of work, or so on are simply
illustrations of it's capabilities with respect to neat ways of
combining various aspects of what Org "is."

Thus, I wouldn't try to pitch these things one way or another ("Org is
great for paralegals" or "Org is the answer for those doing
re-producible research"); I'd simply list what it does as what is "is"
and what it can be used "for" as a way to entice new users and help
get into the top results of some google searches for
tools/solutions/etc..

It seems we all get what it really "is," (TODOs/agenda, universal
markdown -> export to tons of formats, allowing mixing of
prose/code/results, and so on), but are sort of trying to lay claim to
why these tools make it best suited toward some particular field.

Whether you use one of Org's features or all of them, it is what it is
and this can be highlighted in a neat manner and made appealing to
those looking for help in these relevant areas of life.


John

Re: Org Tutorials need more structure

[Charles Millar]

On 9/28/2013 5:52 PM, John Hendy wrote:
> On Sat, Sep 28, 2013 at 4:31 PM, Marcin Borkowski <mbork@wmi.amu.edu.pl> wrote:
>> Dnia 2013-09-28, o godz. 16:50:09
>> Charles Millar <millarc@verizon.net> napisał(a):
>>
>>> On 9/28/2013 3:52 PM, Thomas S. Dye wrote:
>>>> Aloha Carsten,
>>>>
>>> snip
>>>> 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).
>>> Strongly disagree with the sentiment. My undergraduate degree may
>>> gave been Physics, but I work as a freelance paralegal. I use Org
>>> Mode for project (file) planning, scheduling, drafting documents,
>>> etc. Also, I believe that there are some very active participants on
>>> this list who are not scientists and have made great contributions.
>> +1.  Although I'm also a scientist (mathematics), I used Org-mode /once/
>> for science, and it turned out that I felt very much constrained and
>> quickly got back to LaTeX, where I felt much more comfortable.
>> http://octd.wmi.amu.edu.pl/en/Marcin_Borkowski
>> Adam Mickiewicz University
>>
> This is starting to remind me of bike-shedding. Org-mode is a toolbox
> providing various things that can work toward whatever end one wants.
> It's agnostic to field. It doesn't really matter what the end uses are
> -- Org-mode "is" what functions it provides. How those are combined by
> others in various fields, lines of work, or so on are simply
> illustrations of it's capabilities with respect to neat ways of
> combining various aspects of what Org "is."
>
> Thus, I wouldn't try to pitch these things one way or another ("Org is
> great for paralegals" or "Org is the answer for those doing
> re-producible research"); I'd simply list what it does as what is "is"
> and what it can be used "for" as a way to entice new users and help
> get into the top results of some google searches for
> tools/solutions/etc..
>
> It seems we all get what it really "is," (TODOs/agenda, universal
> markdown -> export to tons of formats, allowing mixing of
> prose/code/results, and so on), but are sort of trying to lay claim to
> why these tools make it best suited toward some particular field.
>
> Whether you use one of Org's features or all of them, it is what it is
> and this can be highlighted in a neat manner and made appealing to
> those looking for help in these relevant areas of life.
>
>
> John
>
>
You said it better than I.

Charlie

Re: Org Tutorials need more structure

[Thomas S. Dye]

Aloha John, Marcin, and Charles,

Yes, I completely agree with you. Apologies if my remarks were taken to
be exclusionary in any way. They weren't intended to be. The diversity
of the Org-mode community is one of its great strengths.  

My comments were intended to be ideas on how we might introduce Org-mode
to a wider audience.

In this vein, I think it would be useful to have a brief statement about
Org-mode that gives the interested reader from any background a good
feel for the scope of Org-mode and how it presents itself to the user.
I don't think the current statements about what Org-mode "is" do this
very effectively, though they might have done so in the past.

The "research programming interface" is meant to encompass situations
where all of the software's major components are put to use and thus to
indicate the software's scope.  The bit about scientists likely needs
some qualifications to be absolutely true, but it also prepares the
reader for an interface of a particular kind, one that is logical and
complex rather than "intuitive". The core values bit for me helps
distinguish the Org-mode community from innumerable others we all deal
with every day.

There are probably better ways to give the novice a sense of the
Org-mode experience, but these are the things that stand out for me.  

All the best,
Tom

John Hendy <jw.hendy@gmail.com> writes:

> On Sat, Sep 28, 2013 at 4:31 PM, Marcin Borkowski <mbork@wmi.amu.edu.pl> wrote:
>> Dnia 2013-09-28, o godz. 16:50:09
>> Charles Millar <millarc@verizon.net> napisał(a):
>>
>>> On 9/28/2013 3:52 PM, Thomas S. Dye wrote:
>>> > Aloha Carsten,
>>> >
>>> snip
>>> > 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).
>>> Strongly disagree with the sentiment. My undergraduate degree may
>>> gave been Physics, but I work as a freelance paralegal. I use Org
>>> Mode for project (file) planning, scheduling, drafting documents,
>>> etc. Also, I believe that there are some very active participants on
>>> this list who are not scientists and have made great contributions.
>>
>> +1.  Although I'm also a scientist (mathematics), I used Org-mode /once/
>> for science, and it turned out that I felt very much constrained and
>> quickly got back to LaTeX, where I felt much more comfortable.
>> http://octd.wmi.amu.edu.pl/en/Marcin_Borkowski
>> Adam Mickiewicz University
>>
>
> This is starting to remind me of bike-shedding. Org-mode is a toolbox
> providing various things that can work toward whatever end one wants.
> It's agnostic to field. It doesn't really matter what the end uses are
> -- Org-mode "is" what functions it provides. How those are combined by
> others in various fields, lines of work, or so on are simply
> illustrations of it's capabilities with respect to neat ways of
> combining various aspects of what Org "is."
>
> Thus, I wouldn't try to pitch these things one way or another ("Org is
> great for paralegals" or "Org is the answer for those doing
> re-producible research"); I'd simply list what it does as what is "is"
> and what it can be used "for" as a way to entice new users and help
> get into the top results of some google searches for
> tools/solutions/etc..
>
> It seems we all get what it really "is," (TODOs/agenda, universal
> markdown -> export to tons of formats, allowing mixing of
> prose/code/results, and so on), but are sort of trying to lay claim to
> why these tools make it best suited toward some particular field.
>
> Whether you use one of Org's features or all of them, it is what it is
> and this can be highlighted in a neat manner and made appealing to
> those looking for help in these relevant areas of life.
>
>
> John
>
>

-- 
Thomas S. Dye
http://www.tsdye.com

Re: Org Tutorials need more structure

[John Hendy]

On Sat, Sep 28, 2013 at 6:29 PM, Thomas S. Dye <tsd@tsdye.com> wrote:
> Aloha John, Marcin, and Charles,
>
> Yes, I completely agree with you. Apologies if my remarks were taken to
> be exclusionary in any way. They weren't intended to be. The diversity
> of the Org-mode community is one of its great strengths.
>

I don't take them as exclusionary, just didn't want to see folks going
down a rabbit hole that diverges from the original intent :)

> My comments were intended to be ideas on how we might introduce Org-mode
> to a wider audience.
>
> In this vein, I think it would be useful to have a brief statement about
> Org-mode that gives the interested reader from any background a good
> feel for the scope of Org-mode and how it presents itself to the user.
> I don't think the current statements about what Org-mode "is" do this
> very effectively, though they might have done so in the past.
>

Absolutely love that, and this puts some of your earlier comments in
perspective -- you're looking for the 30sec elevator pitch for
Org-mode, and saying "this outline-y task manager" is not cutting it.

John

> The "research programming interface" is meant to encompass situations
> where all of the software's major components are put to use and thus to
> indicate the software's scope.  The bit about scientists likely needs
> some qualifications to be absolutely true, but it also prepares the
> reader for an interface of a particular kind, one that is logical and
> complex rather than "intuitive". The core values bit for me helps
> distinguish the Org-mode community from innumerable others we all deal
> with every day.
>
> There are probably better ways to give the novice a sense of the
> Org-mode experience, but these are the things that stand out for me.
>
> All the best,
> Tom
>
> John Hendy <jw.hendy@gmail.com> writes:
>
>> On Sat, Sep 28, 2013 at 4:31 PM, Marcin Borkowski <mbork@wmi.amu.edu.pl> wrote:
>>> Dnia 2013-09-28, o godz. 16:50:09
>>> Charles Millar <millarc@verizon.net> napisał(a):
>>>
>>>> On 9/28/2013 3:52 PM, Thomas S. Dye wrote:
>>>> > Aloha Carsten,
>>>> >
>>>> snip
>>>> > 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).
>>>> Strongly disagree with the sentiment. My undergraduate degree may
>>>> gave been Physics, but I work as a freelance paralegal. I use Org
>>>> Mode for project (file) planning, scheduling, drafting documents,
>>>> etc. Also, I believe that there are some very active participants on
>>>> this list who are not scientists and have made great contributions.
>>>
>>> +1.  Although I'm also a scientist (mathematics), I used Org-mode /once/
>>> for science, and it turned out that I felt very much constrained and
>>> quickly got back to LaTeX, where I felt much more comfortable.
>>> http://octd.wmi.amu.edu.pl/en/Marcin_Borkowski
>>> Adam Mickiewicz University
>>>
>>
>> This is starting to remind me of bike-shedding. Org-mode is a toolbox
>> providing various things that can work toward whatever end one wants.
>> It's agnostic to field. It doesn't really matter what the end uses are
>> -- Org-mode "is" what functions it provides. How those are combined by
>> others in various fields, lines of work, or so on are simply
>> illustrations of it's capabilities with respect to neat ways of
>> combining various aspects of what Org "is."
>>
>> Thus, I wouldn't try to pitch these things one way or another ("Org is
>> great for paralegals" or "Org is the answer for those doing
>> re-producible research"); I'd simply list what it does as what is "is"
>> and what it can be used "for" as a way to entice new users and help
>> get into the top results of some google searches for
>> tools/solutions/etc..
>>
>> It seems we all get what it really "is," (TODOs/agenda, universal
>> markdown -> export to tons of formats, allowing mixing of
>> prose/code/results, and so on), but are sort of trying to lay claim to
>> why these tools make it best suited toward some particular field.
>>
>> Whether you use one of Org's features or all of them, it is what it is
>> and this can be highlighted in a neat manner and made appealing to
>> those looking for help in these relevant areas of life.
>>
>>
>> John
>>
>>
>
> --
> Thomas S. Dye
> http://www.tsdye.com

Re: Org Tutorials need more structure

[Suvayu Ali]

Hi,

On Sat, Sep 28, 2013 at 07:29:26PM -0500, John Hendy wrote:
> On Sat, Sep 28, 2013 at 6:29 PM, Thomas S. Dye <tsd@tsdye.com> wrote:
> >
> > In this vein, I think it would be useful to have a brief statement about
> > Org-mode that gives the interested reader from any background a good
> > feel for the scope of Org-mode and how it presents itself to the user.
> > I don't think the current statements about what Org-mode "is" do this
> > very effectively, though they might have done so in the past.
> >
> 
> Absolutely love that, and this puts some of your earlier comments in
> perspective -- you're looking for the 30sec elevator pitch for
> Org-mode, and saying "this outline-y task manager" is not cutting it.

To me the best way to describe Org is: a programmable and dynamic
plain-text note taking platform.  All its features are essentially built
on this ability: planning & task management, authoring or publishing,
literate programming, and what not.  On top of this, it can interact
with external applications for tasks like referencing (links, citation,
etc).  Of course trying to faithfully outline this in a few words is a
herculean task.

-- 
Suvayu

Open source is the future. It sets us free.

Re: Org Tutorials need more structure

[Eric Abrahamsen]

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

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

Those four areas seem pretty distinct and independent to me (except
there's special cross-over between exporting and babel blocks). Any
given prospective org user will probably immediately gravitate to one or
more areas, leaving the others for later. Personally, I immediately
jumped into task management, then went to exporting, and I've only ever
dabbled in babel and spreadsheets. I think it would be good to keep
these areas fairly self-contained.

2 cents,
Eric

Re: Org Tutorials need more structure

[Matt Price]

On Sun, Sep 29, 2013 at 4:44 AM, Eric Abrahamsen
<eric@ericabrahamsen.net> wrote:
> 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
>
> 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).

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.

Very busy the net 2 weeks but afte that I'd like to try to give back a
little bit to the org community, so I could take a crack at some of
these areas (not 3 & 4 though!).

Matt

>
> Those four areas seem pretty distinct and independent to me (except
> there's special cross-over between exporting and babel blocks). Any
> given prospective org user will probably immediately gravitate to one or
> more areas, leaving the others for later. Personally, I immediately
> jumped into task management, then went to exporting, and I've only ever
> dabbled in babel and spreadsheets. I think it would be good to keep
> these areas fairly self-contained.
>
> 2 cents,
> Eric
>
>

Re: Org Tutorials need more structure

[Rustom Mody]

[-- Attachment #1: Type: text/plain, Size: 729 bytes --]

Some years ago I had sent a mail on this subject (Feb 6 2009).  I fished it
out and was editing it (below) and then see that Eric Abrahamsen has said
most what I wanted to say.

Anyways Ive kept the subject list below and want to add only this much:

People come to org for different reasons/needs/inclinations.
It is definitely worthwhile clubbing these diverse/contrasting ways into a
few (5-10?) foci/approaches

My subject list

* Publishing
** Web
** Latex
** Doc

* Brainstorming

* Managing My Data
  own private hyperlink system

* Time/project mgmt
*** Agenda
*** Time tracking
*** GTD
*** Journalling

* Tables and spreadsheets
* Programming (Babel)
** Literate programming
** Reproducible research
** Meta Programming

[-- Attachment #2: Type: text/html, Size: 1120 bytes --]

Re: Org Tutorials need more structure

[Eric Abrahamsen]

Matt Price <moptop99@gmail.com> writes:

> On Sun, Sep 29, 2013 at 4:44 AM, Eric Abrahamsen
> <eric@ericabrahamsen.net> wrote:
>> 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
>>
>> 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.

Re: Org Tutorials need more structure

[Alan Schmitt]

fatkasuvayu+linux@gmail.com writes:

> To me the best way to describe Org is: a programmable and dynamic
> plain-text note taking platform.

I really like this description. Short, and to the point.

Alan

Re: Org Tutorials need more structure

[Eric S Fraga]

Alan Schmitt <alan.schmitt@polytechnique.org> writes:

> fatkasuvayu+linux@gmail.com writes:
>
>> To me the best way to describe Org is: a programmable and dynamic
>> plain-text note taking platform.
>
> I really like this description. Short, and to the point.

but it's missing what for me is the key point which got me into org:
time management!  So how about

  a programmable and dynamic plain-text note taking time management platform
  
but I'm sure somebody else will think something is missing and make
this sentence even longer ;-)

To me, org is like a graph.  A newbie may be attracted to any given node
(time management, note taking, literate programming, database, tables,
spreadsheet, exporting, publishing...) and then move along edges to
other nodes in the graph.  I think any given order of tutorials is
likely to work for some but not others, but so be it?

For me, the info manual is very well structured.  It got me started
quickly but still provided the depth when needed later.

-- 
: Eric S Fraga (0xFFFCF67D), Emacs 24.3.50.1, Org release_8.1.1-7-gaecdf5

Re: Org Tutorials need more structure

[Thomas S. Dye]

Aloha Suvayu,

I like this, too, except that I miss the capabilities of the export
framework.  How about?:

 a programmable and dynamic plain-text note taking platform and markup
 language

All the best,
Tom

Suvayu Ali <fatkasuvayu+linux@gmail.com> writes:

> Hi,
>
> On Sat, Sep 28, 2013 at 07:29:26PM -0500, John Hendy wrote:
>> On Sat, Sep 28, 2013 at 6:29 PM, Thomas S. Dye <tsd@tsdye.com> wrote:
>> >
>> > In this vein, I think it would be useful to have a brief statement about
>> > Org-mode that gives the interested reader from any background a good
>> > feel for the scope of Org-mode and how it presents itself to the user.
>> > I don't think the current statements about what Org-mode "is" do this
>> > very effectively, though they might have done so in the past.
>> >
>> 
>> Absolutely love that, and this puts some of your earlier comments in
>> perspective -- you're looking for the 30sec elevator pitch for
>> Org-mode, and saying "this outline-y task manager" is not cutting it.
>
> To me the best way to describe Org is: a programmable and dynamic
> plain-text note taking platform.  All its features are essentially built
> on this ability: planning & task management, authoring or publishing,
> literate programming, and what not.  On top of this, it can interact
> with external applications for tasks like referencing (links, citation,
> etc).  Of course trying to faithfully outline this in a few words is a
> herculean task.

-- 
Thomas S. Dye
http://www.tsdye.com

Re: Org Tutorials need more structure

[Peter Neilson]

On Mon, 30 Sep 2013 13:01:57 -0400, Eric S Fraga <e.fraga@ucl.ac.uk> wrote:

> but I'm sure somebody else will think something is missing

I'll admit that I've only dabbled in org mode thus far, but here's what I  
see as lacking in the tutorial documentation:

1. Non-video presentations for beginners. Some of us are (for one reason  
or another) badly set up to use video. Perhaps our network connection is  
slow, or our system is flaky and crashes with video. Or perhaps we only  
have five or ten minutes at a time to study. Or perhaps we are mostly  
trying to learn from hard copy we've printed out. A few of us might even  
be blind.

2. Goal-oriented presentations. Instead of telling us, "The XX widget  
allows you to do the YY operation," we might be hoping to see, "To  
accomplish ZZ (for instance, task scheduling), do something like this:  
(neat example with pointers to syntax)"

The user will hope to see examples, even annotated examples. Sometimes  
negative examples: "DON'T try it this way... It seems right, and it's  
alluring, but ultimately it won't work, and you'll never figure out what's  
wrong."

There ought to be discussions of why we should think of the problem THIS  
WAY and not THAT WAY.

It may be that there are portions of the existing docs that cover  
everything I see as deficient, and I've just not found them. Perhaps a  
pointer to LOOK HERE FIRST is needed for those docs.

I'll end with a quotation from a leader in a club to which I once  
belonged: "Yes, I can see how you might think that's a problem. How would  
you like to CHAIR THE COMMITTEE to solve that for next year's convention?"

Perhaps I'm volunteering!

Re: Org Tutorials need more structure

[Eduardo Ochs]

[-- Attachment #1: Type: text/plain, Size: 1579 bytes --]

On Mon, Sep 30, 2013 at 3:36 PM, Peter Neilson <neilson@windstream.net>wrote:

> 1. Non-video presentations for beginners. Some of us are (for one reason
> or another) badly set up to use video. Perhaps our network connection is
> slow, or our system is flaky and crashes with video. Or perhaps we only
> have five or ten minutes at a time to study. Or perhaps we are mostly
> trying to learn from hard copy we've printed out. A few of us might even be
> blind.
>

Any chance of an MP4 version of Carsten's Google Tech talk being
produced and uploaded to a public place, with a wget-able URL? It
would be trivial to add to this tutorial - or to some other - the code
to download it and to make mplayer play it from given positions...

  http://angg.twu.net/eev-intros/find-videos-intro.html
  http://angg.twu.net/eev-intros/find-audiovideo-intro.html

and integrating into Org the feature described there - namely: with a
certain minor mode activated `M-p' opens the current default video at
the first time offset of the current line - should be little more than
a 10-line hack...

Btw, that would make indices of time offsets in videos like the one in

http://orgmode.org/worg/org-tutorials/org-screencasts/org-mode-google-tech-talk.html
http://orgmode.org/worg/org-tutorials/org-screencasts/org-mode-google-tech-talk.org.html

trivial to execute. I don't have (yet) the skills to make things like
=1:23= become active links that do that in Org, though.

Cheers,
  Eduardo Ochs
  eduardoochs@gmail.com
  http://angg.twu.net/#eev
  edrx at freenode.org (at #eev, #org-mode, etc)

[-- Attachment #2: Type: text/html, Size: 3304 bytes --]

Re: Org Tutorials need more structure

[Suvayu Ali]

Hi Alan, Eric, Thomas, and others,

On Mon, Sep 30, 2013 at 06:01:57PM +0100, Eric S Fraga wrote:
> Alan Schmitt <alan.schmitt@polytechnique.org> writes:
> 
> > fatkasuvayu+linux@gmail.com writes:
> >
> >> To me the best way to describe Org is: a programmable and dynamic
> >> plain-text note taking platform.
> >
> > I really like this description. Short, and to the point.
> 
> but it's missing what for me is the key point which got me into org:
> time management!  So how about
> 
>   a programmable and dynamic plain-text note taking time management platform
>   
> but I'm sure somebody else will think something is missing and make
> this sentence even longer ;-)

I'm glad people seem to like it :).  Although I would refrain from
extending that particular sentence.  This is what was going through my
head:

1. What does an Org document look like?  It is primarily a text outline.
2. Is there more to the outline?  Well I can:
   - export it,
   - put metadata on it, like: timestamps, clocks, etc,
   - put TODO markers on it, ... and so on
3. What about the text (content)?  It is really just text, but supports
   a few nifty things.
   - Links to other documents, other applications, executable lisp, etc.
   - It also supports nifty formatting and structural markup.
   - Tables with a deceptively advanced math engine underneath to do
     spreadsheet tasks.
   - Source blocks, optionally which can be evaluated and can interact
     with other text content in the Org file: tables, other source
     blocks, etc.

But then I thought, "Hmm, I can't put all that."  So what is at the
core?  Outline with text, lets just call that notes.  And all the cool
features?  I can use special markup to add enhance the text, aggregate
and filter it, and present it in many ways; that is quite dynamic.  I
can also program it in pretty much any language.

Hence: Org is a programmable and dynamic note taking platform.

This still does not do justice, so lets put in supporting follow-up
sentences highlighting my favourite bits.

Hence my following sentence: All its features are essentially built on
this ability: planning & task management, authoring or publishing,
literate programming, and what not.

Now others can tack on a description for their favourite bit of Org as
supporting sentences.  Anyway, I thought clarifying my thoughts would
help improve the discussion.

Hope this helps,

:)

-- 
Suvayu

Open source is the future. It sets us free.

Re: Org Tutorials need more structure

[Eric S Fraga]

Joseph Vidal-Rosset <joseph.vidal.rosset@gmail.com> writes:
> Hi,
>
> 2013/9/28 Suvayu Ali <fatkasuvayu+linux@gmail.com>
>
>> Your example is not beginner's tutorial at all!  Nor is it something
>> that the manual can cover.
>>
>
> I do not understand why. Every beginner intested in org-mode is interested
> for such or such application, and that's a strange reply to make to a

I think it's partly because many people shudder when they think about
using gnus for the first time.  This is historical.  Gnus is now
relatively easy to set up and use but, in the dim and ancient past, it
was more of a challenge and not something for newbies...  Further, gnus
is still somewhat challenging when it comes to some types of
customisation.  Whether any gnus aspects should be in a beginner's
tutorial is doubtful as it would potentially overwhelm the tutorial!

Of course, many of us on the list are happy to try to help with gnus and
org issues.  

-- 
: Eric S Fraga (0xFFFCF67D), Emacs 24.3.50.1, Org release_8.1.1-7-gaecdf5

Re: Org Tutorials need more structure

[Michael Brand]

Hi Eduardo

On Mon, Sep 30, 2013 at 11:07 PM, Eduardo Ochs <eduardoochs@gmail.com> wrote:
> and integrating into Org the feature described there - namely: with a
> certain minor mode activated `M-p' opens the current default video at
> the first time offset of the current line - should be little more than
> a 10-line hack...
>
> Btw, that would make indices of time offsets in videos like the one in
>
> http://orgmode.org/worg/org-tutorials/org-screencasts/org-mode-google-tech-talk.html
> http://orgmode.org/worg/org-tutorials/org-screencasts/org-mode-google-tech-talk.org.html
>
> trivial to execute. I don't have (yet) the skills to make things like
> =1:23= become active links that do that in Org, though.

See "Audio/video file playback within org mode" on
http://orgmode.org/worg/org-hacks.html

(currently http://orgmode.org/worg/org-hacks.html#sec-3-12)

Michael

Re: Org Tutorials need more structure

[Marcin Borkowski]

Dnia 2013-10-01, o godz. 07:34:14
Suvayu Ali <fatkasuvayu+linux@gmail.com> napisał(a):

> Hence: Org is a programmable and dynamic note taking platform.
> [...]
> Hence my following sentence: All its features are essentially built on
> this ability: planning & task management, authoring or publishing,
> literate programming, and what not.

Why not put this description on orgmode.org?

Best,

-- 
Marcin Borkowski
http://octd.wmi.amu.edu.pl/en/Marcin_Borkowski
Adam Mickiewicz University

Re: Org Tutorials need more structure

[Joseph Vidal-Rosset]

[-- Attachment #1: Type: text/plain, Size: 1228 bytes --]

Hi,

A suggestion : it would be maybe useful , if it is not already done, to
transfer this activity of the list on a forum when one could put "closed"
on a topic, when a solution is done for a beginner like me.

for example, sometime I find very useful help on LaTeX here:

http://www.developpez.net/forums/f149/autres-langages/autres-langages/latex/


I just have the experience that a lot of experts on this list are very kind
and helpful, and the number of closed topic would maybe show more obviously
this fact.


It is just a suggestion, and maybe not a so good idea, I do not know.

All the best

Jo.


2013/10/1 Marcin Borkowski <mbork@wmi.amu.edu.pl>

> Dnia 2013-10-01, o godz. 07:34:14
> Suvayu Ali <fatkasuvayu+linux@gmail.com> napisał(a):
>
> > Hence: Org is a programmable and dynamic note taking platform.
> > [...]
> > Hence my following sentence: All its features are essentially built on
> > this ability: planning & task management, authoring or publishing,
> > literate programming, and what not.
>
> Why not put this description on orgmode.org?
>
> Best,
>
> --
> Marcin Borkowski
> http://octd.wmi.amu.edu.pl/en/Marcin_Borkowski
> Adam Mickiewicz University
>
>

[-- Attachment #2: Type: text/html, Size: 2219 bytes --]

Re: Org Tutorials need more structure

[William Denton]

On 28 September 2013, Carsten Dominik wrote:

> 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?

I'm fairly new to Org; I started just when it moved to version 8.  I'd 
been using outline mode or Markdown for notes and that was good enough for 
the way I managed my tasks, but what drew me over was:

- the compact guide and Organize Your Life in Plain Text, which showed how 
much more Org does than to-do lists
- seeing how I could embed code in a document with Babel, and view images 
inside Emacs
- seeing how I could export to Latex but still make everything look the 
way I like by including my usual header commands

The more I began to use Org for my own notes and research, and saw how 
other people managed their work in it, the more I saw in Org and the more 
I'd try.  (Talks like John Kitchin's sealed the deal.)

I'm grateful to everyone that's helped with the documentation or posted 
snippets on blogs or Stack Overflow ... there are lots of times when I'm 
not sure how to get something working but find a perfect example 
somewhere.

Bill
-- 
William Denton
Toronto, Canada
http://www.miskatonic.org/

Re: Org Tutorials need more structure

[David Rogers]

Suvayu Ali <fatkasuvayu+linux@gmail.com> writes:

> Hi Joseph,
>
> On Sat, Sep 28, 2013 at 09:22:02AM +0200, Joseph Vidal-Rosset wrote:
>> 
>> Example: I am presently mainly interested to see if it is possible to use
>> gnus to write a scientific letter with all conveniences of texlive. Of
>> course I can open a tex file with letter class and send to my colleague a
>> pdf file. But it would be more convenient to write an email and using
>> conversions to html and png images to send to him directly this email. I
>> guess it is possilbe to do it with gnus. But the documentation is esoteric:
>> I hear about links, but how it works concretly with example understanble by
>> a newby ...  mystery. It is therefore frustrating and quickly discouraging.
>
> Your example is not beginner's tutorial at all!  Nor is it something
> that the manual can cover.  For esoteric/specific needs like this
> "advanced tutorials" are more appropriate.

Part of this situation, part of what can be improved about the
tutorials, is that a beginner cannot know whether his request belongs in
a beginner's tutorial or not. Beginners cannot know ahead of time what's
hard and what's easy, and beginners often wonder "Can it do that amazing
thing I've been wishing I could do?" when they see a piece of software
that's new to them.

Face it - Org-mode is ALREADY esoteric in itself, so it's quite
reasonable that beginners will continue to expect it to be able to do
esoteric things that don't happen to be the ones that are already easy -
unless there's a convenient way for them to find out.

-- 
David R

Re: Org Tutorials need more structure

[Marcin Borkowski]

Dnia 2013-10-01, o godz. 13:34:17
David Rogers <davidandrewrogers@gmail.com> napisał(a):

> Suvayu Ali <fatkasuvayu+linux@gmail.com> writes:
> 
> > Hi Joseph,
> >
> > On Sat, Sep 28, 2013 at 09:22:02AM +0200, Joseph Vidal-Rosset wrote:
> >> 
> >> Example: I am presently mainly interested to see if it is possible
> >> to use gnus to write a scientific letter with all conveniences of
> >> texlive. Of course I can open a tex file with letter class and
> >> send to my colleague a pdf file. But it would be more convenient
> >> to write an email and using conversions to html and png images to
> >> send to him directly this email. I guess it is possilbe to do it
> >> with gnus. But the documentation is esoteric: I hear about links,
> >> but how it works concretly with example understanble by a
> >> newby ...  mystery. It is therefore frustrating and quickly
> >> discouraging.
> >
> > Your example is not beginner's tutorial at all!  Nor is it something
> > that the manual can cover.  For esoteric/specific needs like this
> > "advanced tutorials" are more appropriate.
> 
> Part of this situation, part of what can be improved about the
> tutorials, is that a beginner cannot know whether his request belongs
> in a beginner's tutorial or not. Beginners cannot know ahead of time
> what's hard and what's easy, and beginners often wonder "Can it do
> that amazing thing I've been wishing I could do?" when they see a
> piece of software that's new to them.

Well, in case of Org-mode, surprisingly often the answer is "Yes, it
can." ;)

> Face it - Org-mode is ALREADY esoteric in itself, so it's quite
> reasonable that beginners will continue to expect it to be able to do
> esoteric things that don't happen to be the ones that are already
> easy - unless there's a convenient way for them to find out.

I woudn't call Org-mode "esoteric".  For Emacs users, it is quite a
natural thing.  For non-Emacs-users, maybe, but still, its simplicity
and newbie-friendliness is amazing (deceptively, I'd call it;)).

Best,

-- 
Marcin Borkowski
http://octd.wmi.amu.edu.pl/en/Marcin_Borkowski
Adam Mickiewicz University

Re: Org Tutorials need more structure

[M]

Hi Carsten & all, 

thanks for this good idea and the resulting discussion here!

my 2 cents about the tutorials page:
yes, I agree, that especially for absolute beginners (new to Emacs and new
to org-mode) it would be helpful to have a very basic step by step tutorial.
The list of "General introductions" is very long and quite confusing.

How I came to using org-mode?

I am a newby (at least I still feel like one, although I'm working with
Emacs org-mode now for more than 1.5 years), so maybe my experience might
help here.

I was a GTD user at first using other "GUI oriented" GTD software like
Thinking Rock, iGTD. iGTD had some problems and was not updated any more, so
I started searching for a new tool  and found Charles Cave's GTD tutorials
[1] (nearly 3 years ago, it seems!) and then started using org-mode since
Jan 2012. 
I then found Bernt Hansen's excellent site and used his setup [2] for my
first steps with org-mode, but it was very hard to adapt the agendas and
settings to my needs (and I'm still struggling).
Furthermore, Sacha Chua's blog is very interesting and I'm often looking at
the worg tutorials page.

So my first interest was todo/task/project management, but I quickly became
interested in note-taking, exporting, attachments, dired, bookmarks,
linking, ...

My problems were (and still are):
a) I am one of those users, which have never been really working with Emacs
before, so at the beginning, it's very hard to understand the concept and
basic commands.
Many tutorials take for granted a lot of knowledge.

b) I'm using two different OS's (Windows 7 at work and OS X 10.6 at home),
each one has its own problems when setting up advanced features.
It is especially difficult, to set up an efficient workflow to integrate MS
Outlook (Mails/Calendar) and Emacs org-mode...

c) I'm only an engineer, not a professional programmer. My knowledge about
programming in general and elisp and Emacs configuration is still very
limited, unfortunately. see a)

[1] http://members.optusnet.com.au/~charles57/GTD/gtd_workflow.html
[2] http://doc.norang.ca/org-mode.html

Nevertheless thank you for this great tool and all the work you all put in
maintaining, extending, documenting and helping!
Org-mode changed my way of working and I never was so close to having a good
and efficient system as I am now with org-mode. (as soon as long as I don't
have to search for the solution of a problem :( )

Kind regards

Martin 


Carsten Dominik <carsten.dominik <at> gmail.com> writes:

> and came away with the feeling that that this page has become
> somewhat useless for people who are really new to Org.
> 
> 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?

Re: Org Tutorials need more structure

[Alan E. Davis]

[-- Attachment #1: Type: text/plain, Size: 3508 bytes --]

To be brief, the tutorials and other parts of the worg webpages could do
with some updating.   Org-mode has been through a good amount of evolution.


One isolated example is the "remember" tutorials.  These could, at the
least, be marked with a paragraph inset at the top of the file: a statement
that this feature has been supplanted by the "Capture" feature, but that
the tutorial is still useful for basic usage ideas.

IMHO

Alan


On Tue, Oct 1, 2013 at 6:10 PM, M <Elwood151@web.de> wrote:

> Hi Carsten & all,
>
> thanks for this good idea and the resulting discussion here!
>
> my 2 cents about the tutorials page:
> yes, I agree, that especially for absolute beginners (new to Emacs and new
> to org-mode) it would be helpful to have a very basic step by step
> tutorial.
> The list of "General introductions" is very long and quite confusing.
>
> How I came to using org-mode?
>
> I am a newby (at least I still feel like one, although I'm working with
> Emacs org-mode now for more than 1.5 years), so maybe my experience might
> help here.
>
> I was a GTD user at first using other "GUI oriented" GTD software like
> Thinking Rock, iGTD. iGTD had some problems and was not updated any more,
> so
> I started searching for a new tool  and found Charles Cave's GTD tutorials
> [1] (nearly 3 years ago, it seems!) and then started using org-mode since
> Jan 2012.
> I then found Bernt Hansen's excellent site and used his setup [2] for my
> first steps with org-mode, but it was very hard to adapt the agendas and
> settings to my needs (and I'm still struggling).
> Furthermore, Sacha Chua's blog is very interesting and I'm often looking at
> the worg tutorials page.
>
> So my first interest was todo/task/project management, but I quickly became
> interested in note-taking, exporting, attachments, dired, bookmarks,
> linking, ...
>
> My problems were (and still are):
> a) I am one of those users, which have never been really working with Emacs
> before, so at the beginning, it's very hard to understand the concept and
> basic commands.
> Many tutorials take for granted a lot of knowledge.
>
> b) I'm using two different OS's (Windows 7 at work and OS X 10.6 at home),
> each one has its own problems when setting up advanced features.
> It is especially difficult, to set up an efficient workflow to integrate MS
> Outlook (Mails/Calendar) and Emacs org-mode...
>
> c) I'm only an engineer, not a professional programmer. My knowledge about
> programming in general and elisp and Emacs configuration is still very
> limited, unfortunately. see a)
>
> [1] http://members.optusnet.com.au/~charles57/GTD/gtd_workflow.html
> [2] http://doc.norang.ca/org-mode.html
>
> Nevertheless thank you for this great tool and all the work you all put in
> maintaining, extending, documenting and helping!
> Org-mode changed my way of working and I never was so close to having a
> good
> and efficient system as I am now with org-mode. (as soon as long as I don't
> have to search for the solution of a problem :( )
>
> Kind regards
>
> Martin
>
>
> Carsten Dominik <carsten.dominik <at> gmail.com> writes:
>
> > and came away with the feeling that that this page has become
> > somewhat useless for people who are really new to Org.
> >
> > 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?
>
>
>
>
>

[-- Attachment #2: Type: text/html, Size: 4515 bytes --]