Just thinking out aloud here as I read about your writing *before* your Aha. Is it possible to integrate the concept of chapters as you write your executable documents and are 'Composing script lists from a tree of nodes'? The idea appeals to me and it also possibly reveals how little I know about programming. But hey, of course that has nothing to do with aha moments and thinking out aloud.
Lewis On Saturday, February 11, 2017 at 12:18:40 AM UTC+11, Edward K. Ream wrote: > > > On Thu, Feb 9, 2017 at 10:55 AM, Edward K. Ream <edre...@gmail.com > <javascript:>> wrote: > > > > The feeling is that good docs may be akin to small chunks of code > ... > > At some point in the last day or so, the phrase *executable docs* popped > into my head. Is that phrase itself 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. > -- 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.
