On Thu, Feb 9, 2017 at 10:55 AM, Edward K. Ream <edream...@gmail.com> wrote:
> The feeling is that good docs may be akin to small chunks of code ... > I'm pretty sure there is a breakthrough nearby. Yesterday I started work on "real" slides. In the process, I completed debugging of demo.py, as explained here <https://groups.google.com/d/msg/leo-editor/GJLejpPnSGk/CGOCMrMhCAAJ>. Hmm. The rest of this post is pretty much thinking out loud. You could call it an Engineering Notebook post. Ignore it if you like, but if you read on you will be in on the *exact moment* at which an important new Aha appeared. Note: I wrote this next paragraph *before* the Aha appeared. Imo, breakthroughs aren't real unless you can describe *exactly the instant* the Aha occurred. No, you don't have to remember the time at date at which it happened, but you have to be able to clearly describe the moment. Understand? At some point in the last day or so, the phrase *executable docs* popped into my head. Is that phrase itself is a breakthrough? I'm not sure. [No it's not, but it's close]. What *is* clear is that I've never before had so much energy writing docs, or really, writing anything. Clearly, the "less said the better" principle is a key ingredient. And so is intermixing words with example code. It's kinda like using FAQ style for *everything*. Another thing that is clear to me now. Composing script lists from a tree of nodes, each node of which can contain multiple demo scripts, is a *huge* breakthrough. And it's one of the strengths of org-mode. Clearly, the phrase "executable documentation" perfectly describes the script tree that drives a demonstration. There is so much energy involved: 1. It's now dead easy to create and edit nodes. 2. Each node naturally describes one slide, or one thought. 3. Setup and teardown methods eliminate repetitious code from nodes. 4. Testing is instantaneous. Just run the demo. As I write this, I see that it might be useful to associate names with slides. That way, we could tell demo.start to start with the slide of a given name. *The big question* Debugging demo.py has been great fun. And the ideas keep coming, as just mentioned. But the big question is the following: *will demo.py help me to create better tutorials?* I think the answer is yes, for several reasons. 1. It's *much* easier to create callouts with demo.py than with Camtasia. As a result, I can create hundreds or thousands of experimental slides to see what works. Now, I can focus on *what* I want to say, without production overhead. 2. The new demo.py plugin does not interfere with the rest Leo in *any* way. This means that demo scripts can automate *all* aspects of Leo's operation. In this regard, it's unlikely that any subtle bugs exists in the Demo class. The reason is simple: all the code is dead simple. 3 As a result, I can attempt things in demos that would have been out of the question previously. Demos can show how I really work, in real time, or in "slow motion". I can revise them endlessly until they *work* just exactly as I want.* And that's the Aha I have been looking for!* The Aha is this: writing demos is about getting Leo to *work* (as controlled by the demo script) in a way that *shows* something properly. The magic word is "works". In other words, demos don't *tell *about Leo, they *show *how Leo *works*. There is a debugging process involved, both mental and operational. As a result demos have exactly the same energy level as writing a program, because I *am* writing a program. Ok, now that I see the Aha, there is one more point to make: 4. Improving a video with even a good tool like Camtasia Studio is a soul-draining endeavor. It's just way too much work to futz with post-production details. In contrast, creating demos with demo.py involves only *pre-production* work. To revise a video, just revise the demo script, and re-record. That's *all*. Notice, there is no real temptation to record a video at all until everything "just works". My task is now clear. Create demos that* show Leo in action*! Edward P.S. Last night another thought appeared. It may have had something to do with the Aha just described. The thought is that we don't need (or want) fancy arrows in a demo. Instead, the demo should *itself *be an animation that highlights what we want to explain. It's close to the Aha, but isn't it. 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 leo-editor+unsubscr...@googlegroups.com. To post to this group, send email to leo-editor@googlegroups.com. Visit this group at https://groups.google.com/group/leo-editor. For more options, visit https://groups.google.com/d/optout.
