I wonder if there's a fifth function missing from the list, especially if one construes 'documentation' broadly as 'what a person wants to be able to find out about the tool'. I'm torn between calling it Invitation or Questions, but it's basically "What sorts of things can this program, or feature, do for me; why might I want to invest in learning it?"
Leo seems to me to be somewhat lacking here, especially at its growing points. An example that bothers me particularly: I was happy when I read that Leo now supports jupyter notebooks. But I've tried to go through the documentation carefully and I can't discover what the support consists of. How can Leo enhance how I use a jupyter notebook? The sort of thing I envisage goes: "Can I do this useful (for my end purpose) thing with Leo?" "Yes: there is a module called yyy that can help you do that sort of thing. Here's a sketch of how." Scripting seems to be another candidate: start with an ability that a newbie can see an immediate use for, and demonstrate the script that accomplishes it. Make this the first thing in the tutorial perhaps (so maybe what I'm saying is that tutorials would work better if they made it clear at the start why one might want to take them?) Or there are other projects discussed in this group (ViewRendered, pyzo, ...) that I have paid no attention to because I never found a statement of what they could do for me or how they could enhance what I want to do. Saying this in yet another way, I was struck ages ago by a sentence of Edward's: "After that, leoPyRef.leo contains all the answers." To which my immediate response was: "Yes, but where do I find the questions (for end-use purposes) that Leo offers good answers to?" - geoff On Saturday, 26 October 2019 19:05:57 UTC-2:30, Matt Wilkie wrote: > > Found by way of Guido von Rossum in python discussion forum: > https://www.divio.com/blog/documentation/ > > Basically: recognize there are 4 kinds of documentation, serving different > functions. Design, write and store them differently. It's in mixing them up > in one document/place that leads to mess and confusion on both the author > and consumer side. The four are: Tutorials, How-to's, Explanations, and > Reference. > > I found it to be a good read and intend to see how I can apply it to my > work. > > -matt > -- 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 view this discussion on the web visit https://groups.google.com/d/msgid/leo-editor/31426ca4-7f52-4b6d-9ad0-8fd7d82be57c%40googlegroups.com.
