Leo in 5 minutes

[Edward K. Ream]

Here is the first draft for a new intro to Leo's tutorials, Leo in 5 minutes.  Let me know what you think.

Outlines

Leo is a full-featured outliner and IDE, with features borrowed from emacs and vim. When Leo reloads an outline, it remembers where you left off.

Outlines consists of nodes with headlines and bodies. The outline pane shows nodes. The body pane contains the body of the selected node.

External files

- @file trees in the outline represent external files on your file system. Leo updates @file nodes when you change external files outside of Leo.

- When saving an outline, Leo writes all changed @file trees to their external files.

Scripting and markup

- Leo's markup language consists of`@others` and `<< sections >>`. Markup controls how Leo writes @file trees to external files.

- Any outline node can contain a python script. Three predefined symbols give Leo scripts easy access to all the structure and data in the outline.

- The same markup applies to scripts as well as external files. Before executing a script node, Leo composes the script from the script node and (depending on markup) some or all of its descendants.

- @button nodes contain scripts that can be applied to other nodes.

Clones

- Outline nodes can be cloned. Cloned nodes are actually the same node, but they appear in different places in the outline. Changes to any clone affect all other clones of that node, including their descendants. Clones are a powerful organizing tool.

- Leo's clone-find commands create clones of all found nodes. The clone-find commands move the newly-created clones so they are all children of an organizer node describing the search.

Summary

@file nodes create external files. Guided by markup, Leo writes @file trees to external files. Leo updates @file trees when external files change outside Leo. Leo's importers create outlines from external files.

Leo composes complex scripts from a node and (depending on markup) some or all of its descendants. Leo scripts have access to all data in the outline, including its structure.

Clones are nodes that appear in multiples places within the outline. Leo's clone-find commands gather found nodes together in one place.

Ironic Comments

The "less said the better" principle has allowed me, for the first time ever, to summarize Leo's essential an unique features in just a few words. This summary probably seems pretty clear to Leonistas. However, I wonder how much newbies will understand.

There are two ways forward.

1. Explain the pithy summary above using text examples, including text representations of Leo's outline structure. We must do this for the written docs, but text only hints at Leo's dynamic nature.

2. Use this post as a preliminary script for a demo, eventually to appear on YouTube. I'll attempt this soon.

Your comments and suggestions, please.

Edward

[john lunzer]

I think what you said about the "over the shoulder" concept of learning is potentially the most powerful way to bring people up to speed. Some people will still prefer traditional "read the docs" style documentation but many will prefer narrated "demo.py" style demos showing them exactly what Leo is capable of.

I believe YouTube is the best place host these demos as it offers the "playback speed" setting which in my experience has been critical to me watching any technical/instructive videos.  

[Edward K. Ream]

​​

​​

​On Sat, Feb 11, 2017 at 8:36 PM, john lunzer <lun...@gmail.com> wrote:

​> ​

I think what you said about the "over the shoulder" concept of learning is potentially the most powerful way to bring people up to speed.

​

​I agree completely, but... Looking over the shoulder involves asking questions. Neither text nor videos are proper substitutes.

tl;dr: See the summary. I don't want to spoil the presentation of two important Ahas.

In my original post I said:​

​>> ​

There are two ways forward

​...

​1. Explain the pithy summary above using text examples

​...

​2. Use this post as a preliminary script for a demo

​...​

​Soon after I wrote this I had a Eureka moment. The "less said the better" principle isn't just about "Omit needless words". Neither examples, nor even videos, are the heart of the matter.

The Aha is:

    Think visually

That's it.  That's what I have been missing about docs.

Let's apply this to Leo.

First, Leo's home page must be more inviting. Could it be that the "Learn about Leo in two hours" link is a tad intimidating?

Instead, the link should be something like:

    5 pictures introducing Leo

or maybe:

    Learn about Leo in 5 minutes

As I write this, I think I prefer the second.  Yes, visuals are the Aha, but people actually do want to get a feel for new tools quickly.

Anyway, this link will take people to one or more pages that introduce people to Leo with pictures. Pictures showing:

- Leo's main window

- @file nodes with markup

- Scripts with markup

- Find command.

- Clones and cff

- Bookmarks plugin.

A few pictures for each topic.

And this leads me to a second Aha. In the last day or so, I've seen that, for me at least,

    Pictures are better than videos

They are easier to understand, and easier to remember.

Let me give you an example. The org mode is awesome video is good.  No doubt about it.  But aside from the introductory "exploding text", I don't remember too much real action.  Instead, I remember these things:

1. Ctrl-C callouts kept popping up.  They weren't explained, but yeah, I get it that Ctrl-C is somehow important :-)  In other words, I remember the picture (in my mind) of the Ctrl-C callout.

2. I remember the (static!) page that contained something like this:

#+BEGIN_SRC python :tangle hello_world.py
print('Hello world')
#+END_SRC
...
#+BEGIN_SRC emacs-lisp
(org-babel-tangle)
#+END_SRC
...
#+BEGIN_SRC sh
javac hello.java
#+END_SRC

And that's about all I understood or remembered from the video.  Yes, that was enough to convince me that org mode is heavy competition to Leo.  But the video actually didn't teach me all that much in 18 minutes...

The plan

1. I shall design, with pencil and paper, the pictures that will introduce people to Leo's key features.

At root, Leo isn't that complex, and isn't that hard to understand.  How could not be true? I created @others and sections naturally, and they haven't changed much in almost 20 years!

2. I'll use the demo plugin to create the static pictures in Leo.  Then I'll just use Alt-Screenshot to paste the screenshot to the clipboard, and use Inkscape to create the file. Probably no need to use the baroque screenshot plugin.

3. (most important) I'll create plain html pages that intermix the screenshots with something like the pithy text in my original post on this thread.

Summary

Aha 1: Think visually.

Good documentation isn't primarily about omitting needless words. Yes, examples are important.  But the fundamental principle is that good docs present material visually.

Hmm.  As I edit this, I wonder how this Aha sits with the idea stories are the heart of communication.  See the book, Made to Stick, about which I have written.  But, hehe, all I remember about the book is that it has duct tape on the cover! That picture stuck with me much better than the stories.

So yes, maybe the intro docs should be organized around tasks (stories), but the communication will happen mainly via pictures.

Aha 2: Pictures are better than videos.

Pictures present concepts faster and more clearly than videos. As discussed in the Post Script, people have a virtually unlimited capacity to remember pictures. The same can not be said, in general, for videos.

The plan: design screen shots with pencil and paper, set them up with the demo plugin, take them with Alt-ScreenShot, and put them in introductory web pages that contain pithy text.

Looking over a friend's shoulder is so effective because the learning can ask questions.  That's why something as complex as Emacs continues to be popular.

Edward

P.S. Experiments leave no doubt that almost everyone has a stupendous ability to remember pictures. I may have written about this before.

Indeed, the following task is easy for most people:

1. Show people 20 pairs of pictures, for a few seconds each.

2. Later, say after 10 minutes, show people another set of 20 pairs of pictures.  In each pair, one of the pair is from the first set of pictures, and one isn't.  The task is to pick the picture that was in the first set of pictures.

I easily got 20 out of 20. Most people do as well. There seems to be no limit to people's capacity to remember (static) pictures.  MIT undergrads were shown pairs of pictures for three hours. When tested later, their recall rates were over 90 percent!!

I have thought about this many times since. We all can have great memories if we can tie the to-be-remembered item to a picture.

I seriously doubt that our memory for videos is as good.

EKR

[lewis]

A big tick for way forward number 1.
Text examples provide clarity for a feature with no room for misunderstanding. This especially applies to directives.

I believe text examples support your "less said the better" principle better than any other method.

I can appreciate a good video tutorial but IMHO there is nothing better than clean well formatted text. You don't have to toggle the play/pause buttons :/

Regards
Lewis

On Sunday, February 12, 2017 at 9:44:59 AM UTC+11, Edward K. Ream wrote:

Here is the first draft for a new intro to Leo's tutorials, Leo in 5 minutes.  Let me know what you think.

[snip]

[lewis]

Aha 1: Think visually.
sounds good

Aha 2: Pictures are better than videos.

Supported by clear text examples sounds even better :)

Your recent demo.py plugin markdown document is very well presented, with really nice code formatting. It could benefit enormously from pictures at all the right places.

Lewis

[Edward K. Ream]

​Interesting thought.  I'll review.

Edward

[Edward K. Ream]

On Sun, Feb 12, 2017 at 7:22 AM, Edward K. Ream <edre...@gmail.com> wrote:

Your recent demo.py plugin markdown document is very well presented, with really nice code formatting. It could benefit enormously from pictures at all the right places.

​Interesting thought.  I'll review.

​I've look through the docs.  Most of the text snippets could be called pictures of body text. The only place I found that might benefit from a real picture is the example of the top-level script. A screen shot would show the actual @button node and its children.

Do you have any other "right places" in mind?

Edward

[Edward K. Ream]

On Sunday, February 12, 2017 at 4:48:46 AM UTC-6, Edward K. Ream wrote:

I'll create plain html pages that intermix the screenshots with something like the pithy text in my original post on this thread.

When I look at the basic leo slideshow with fresh eyes (I haven't looked at it in years) I am struck by how tedious it is. The signal/noise ratio is way too low. My goal is to replace it with just a few screenshots and a few words.

To repeat. The basics of Leo are simple. It's pointless and counter-productive to make a big deal out of something fundamentally simple.

I suspect the same remarks apply to all the slideshows here, and most of my own videos. I'll be working on this project this week.

Edward

[Edward K. Ream]

On Sunday, February 12, 2017 at 9:30:54 AM UTC-6, Edward K. Ream wrote:

When I look at the basic leo slideshow with fresh eyes (I haven't looked at it in years) I am struck by how tedious it is. The signal/noise ratio is way too low. My goal is to replace it with just a few screenshots and a few words.

And all on a single page. A few smallish screenshots won't make the page daunting to read.  Why have a full-blown slideshow (or a video) if a single page suffices?

Edward

[rengel]

The "less said the better" principle has allowed me, for the first time ever, to summarize Leo's essential an unique features in just a few words. This summary probably seems pretty clear to Leonistas. However, I wonder how much newbies will understand.

These 'Ironic Comments' are very much to the point. Your post is a nice summary of the main features of Leo for somebody who already knows what Leo is all about. A newbie probably would understand nothing.
Of course, this begs the question: Whom do you consider a newbie?

Tutorials are a kind of instructional material.

The first and foremost question when devoloping instructional material is:
Whom do you want to adress? What is your target audience?
(Non-IT-people, writers, Java programmers, programmers in general, Emacs fans, Pythonistas, etc.)
Second you need to ask, what these people need to learn in order to perform certain tasks.
Then, and only then, you can ask how you might accomplish this (using text, videos, pictures, screenshots, etc.).

In a former life I have developed a lot of instructional material. What helped me to get a grip on my procedures and to get a clear picture, on what topics to select or dismiss, were a couple of rather small books (around 130 pages or less) by Robert F. Mager, one of the outstanding American pedagocical psychologists (https://en.wikipedia.org/wiki/Robert_F._Mager):
- Goal Analysis
- Preparing Instructional Objectives
- Devoping Vocational Instruction

Just some remarks...

Reinhard

[Offray Vladimir Luna Cárdenas]

I like the short nature of the tutorial and I don't think they're targeted towards people who already know Leo or are developers, as Rengel said in this thread,  except for the parts that introduce Leo in reference to emacs and vi, so would be needed some more explanation to non-developers and add some links to markup languages and expand the introduction of external files. Why they are important in the Leo context? How Leo can help you to (de)construct external files. I agreed with Rengel that defining the target of documentation is important instead of leave them implicit (only developers which are, in some way familiar with Vim and emacs?).

I think that it is important to show examples of the Leo markup and the programmability capabilities of the tree/document. Org mode introduce this for a "general" population with the TODO examples or for a more specific one with literarate devops. At this moment, I'm making the Grafosfocopio manual and my idea is to present generalities of it (installation, outlining, node parts, and special keywords, markdown and PDF export) and use the static PDF manual as an invitation to explore the interactive examples included with the environment. I have found that providing a functionality to update the documentation and the software independently is pretty useful to test both. May be Leo could include a functionality to download the tip version of its documentation, and when makes sense, put demo.py (or demo.leo) there.

Cheers,

Offray 

--
You received this message because you are subscribed to the Google Groups "leo-editor" group.
To unsubscribe from this group and stop receiving emails from it, send an email to leo-editor+...@googlegroups.com.
To post to this group, send email to leo-e...@googlegroups.com.
Visit this group at https://groups.google.com/group/leo-editor.
For more options, visit https://groups.google.com/d/optout.

[Offray Vladimir Luna Cárdenas]

I meant the 5 minutes tutorial :-).