On Sat, Feb 11, 2017 at 8:36 PM, john lunzer <[email protected]> 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 <http://www.investmentwriting.com/2011/03/omit-needless-words-excerpt-from-strunks-the-elements-of-style/>". 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 <https://www.youtube.com/watch?v=fgizHHd7nOo> 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 <https://en.wikipedia.org/wiki/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 -- 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 [email protected]. To post to this group, send email to [email protected]. Visit this group at https://groups.google.com/group/leo-editor. For more options, visit https://groups.google.com/d/optout.
