The process of documentation is starting to feel a lot simpler. The following amount to a collapse in complexity:
Part I: Workflow 1. The screenplay must come first, and it must be separate from post production. Indeed, there is no need for Wink until all slides have been *completely* scripted. 2. It is useful, when writing an @slideshow script (that is, the @slide nodes), to act "as if" I were using Wink. That is, it is useful to go through, in Leo itself, the steps that comprise the slideshow. Mistakes matter not at all, but actually seeing what I am writing about is surprisingly effective. It's a major help in continuity. 3. Leo's usual organizational methods apply to slideshows: we want to group slides into "units". How that is actually done is (mostly) a matter of post production, so we can *ignore* such details while writing. I'll just "scribble away" on @slide nodes and feel free to use organizer nodes at will. How it will actually generate html pages can (and should) be left for later. Part II: Writing 1. Introductory slides should *do something*, rather than describe or define. 2. In fact, *implicit definitions* are actually much *clearer* than laborious "formal" explicit definitions. Points 1 and 2 are a huge change in my thinking. 3. We want to make the writing as as matter-of-fact and simple as possible, not just to save work, but to ensure that we actually document *everything* useful. 4. The "command voice" (do this, do that, aka comments style), solves several vexing problems. It is active without specifying the subject. Thus, there is no need to choose, moment by moment, whether the subject is "I" or "you". Furthermore, commands imply action, not description. 5. Eventually, *everything I do with Leo* should be shown in a slideshow somewhere. In other words, everything must be defined, if only implicitly. This would be a large task without the simplifications I have just described. 6. Showing "everything" is the one and only antidote for "the curse of knowledge". Included in "everything" will be at least the following: - How to install Leo. - How to start Leo. - How to do all common tasks with outlines. - How to create views with clones. - How to create external files. - How to script outlines. Some of these are complex topics. We'll want to show the organization on the web site much as in a Leo outline. This will involve post- production work, most probably a slide-oriented sphinx theme. For example, the discussion of outlines must include insert, delete, select, move, undo and focus. Most of these will be subsidiary slideshows. For example, selecting nodes involves keystrokes, which in turn involves pane-specific key bindings. There is a *lot* to illustrate. I'll certainly want to ensure that everything I do on a typical day gets discussed. Summary This post tells how writing Leo documentation as (nested) slideshows suddenly seems easier. The writing seems easier, less fraught with choices, and the writing is now divorced from Wink and sphinx. There should be no more endless tweaking of slides before the writing is complete. Edward -- You received this message because you are subscribed to the Google Groups "leo-editor" group. To post to this group, send email to [email protected]. To unsubscribe from this group, send email to [email protected]. For more options, visit this group at http://groups.google.com/group/leo-editor?hl=en.
