> All questions and comments are welcome. >
I hope so. Let me play the Devil's Advocate. On the first page of the new tutorial, we find (highlights by me): Leo is a full-featured outliner. Unique features make Leo a powerful IDE, > Personal Information Manager and scripting environment. *The first three > tutorials are for everone:* > > I take your word for it. Suppose I'm an intelligent lay person (say a professional like a doctor, a lawyer, a journalist, a writer) who is looking for computer-based tool to manage her personal and business information. Do you really expect that such a person understands, what *a full-featured outliner*, *a powerful IDE* or a *scripting environment* ist? So the first look at the tutorial tells me: This tool is probably not for me. Cased closed. But assume, I made it to the second page titled 'Leo in 10 minutes: Leo’s most important features <http://leoeditor.com/tutorial-basics.html>': It starts with a quotation that only die-hard programmers understand. That doesn't 'intrigue' professional people who have too much to do and too little time. The Contents contain too many technical terms that a lay person doesn't know (Leo directives, clones, External files, Plugins, API, DOM,...). In documentation, you have to speak the language of target audience. That's why it is important to use different approaches for different target audiences and to define them in the first place. As John Lunzer already mentioned: The screenshot needs to be updated - again, for each target audience differently. To a lay person it just looks like Greek. The body pane shows something that only insiders recognize as XML. The average person doesn't abstract from concrete content. The description below the screenshot is way too technical and less said is not always better. You are using a lot of bolded faced terms, supposedly to mark places where they are defined. One has to understand that these are meant to be definitions. A proven technique in manuals and books is just to say what which typeface means. Leo’s main window consists of an *icon area* just below the menus, an *outline > pane* at the top left, a *log pane* at the top right, a *body pane* at > the bottom left, Normally, I don't nitpick on such small details. But this is supposedly an introductionary tutorial for people who've never heard of these terms. Don't the menus belong to Leo's main window? Well, I don't see an *icon area*, because there are just to arrow buttons, a drop-down button and some other things that might be buttons or tabs. BTW: The common term for this area is toolbar. So I would do it: Leo's *main window* has the familiar look of many Window applications. At > the top are the *common menubar* and *toolbar*. The large main area, > where the most work is done, appropiately is called the *workspace*. It > is divided into three main subareas. Suppose you are working on some > documents. Then the top left subarea shows an overview of all your > documents and/or the inner structure of a document. Such a structured > display also is called an *outline*, and thus this area is called the > *outline > pane*. > and similar for the other subareas. In this manner, you get a gentler introduction of the key terms using a language a newbie (probably) understands. and an optional *viewrendered pane* at the bottom right. Huh? Reminds me of 'What's Aleppo?' What is *viewrendered*? > The *minibuffer* and *status line* lie at the bottom of the main window. And after all these years the *command line* (at term that most people would understand) is still called a *minibuffer* (a term that must be explained to any newbie). For an introduction you might say: At the bottom of the window is a special area that is one row high and > reserved for reserved commands that advanced users can exceute > interactively. This area is called the *command line*. > The last row of the window is the so called *status line*, that is > familiar to most computer users. > You execute commands by name from the minibuffer, as in emacs and vim. This doesn't belong in an introductory text for everybody. I could go on, but as you said: Life is too short. It's simple: Just imagine what a newcomer to any of the topics might or might not know. Reinhard -- 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.
