Guide to writing better software documentation

[Matt Wilkie]

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

[rengel]

Thank you for this link! Great article and video!

I can only recommend to study this article and the video.

One application might be to denote or tag each page of Leo documentation with TUT (Tutorial), HOW (How-to- Guide), EXP (Explanation or Discussion), and REF (Reference).

It helps to separate, clarify, and delimit what one wants to say/write on a particular page.

Reinhard

[Offray Vladimir Luna Cárdenas]

Thanks for the link Matt.

For me how-tos and tutorials are kind of mixed and I think that the examples don't work well to create a good boundary (teaching a small child how to cook and a recipe in a cookery book can do kind of the same). Also learning and understanding are not good boundaries for Tutorials and explanation. I would say that, following the context, one is procedure oriented and the other is context oriented (but both help to learning and understanding).

Anyway, is a good resource to think how to improve technical writing.

Cheers,

Offray

--
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+...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/leo-editor/f3537245-369b-494e-94e2-3df43296b2d1%40googlegroups.com.

[Edward K. Ream]

On Sat, Oct 26, 2019 at 4:36 PM Matt Wilkie <map...@gmail.com> wrote:

Found by way of Guido von Rossum in python discussion forum:

https://www.divio.com/blog/documentation/

Tutorials are learning oriented.

How-to's are goal oriented.

Explanations are understanding oriented.

References are information oriented.

I think this is useful.

Edward

[rengel]

On Monday, October 28, 2019 at 4:16:32 PM UTC+1, Offray Vladimir Luna Cárdenas wrote:

...

For me how-tos and tutorials are kind of mixed and I think that the examples don't work well to create a good boundary (teaching a small child how to cook and a recipe in a cookery book can do kind of the same).

Did you watch the video? It might help to clarify the boundaries...

Reinhard

[Matt Wilkie]

I agree Tutorial and How-To division could overlap in some contexts. The takeaway for me was separating Explanation and Reference from both. I've watched many of my guides get tangled up and end up more confusing when I mix 'splaining and recipe-ing in particular. I'm happy to have new lenses to look at these as different types with distinctly different purposes.

-matt

[Rob]

Thanks for posting the link! I don't write software documentation. However, this is helpful for me as I write documentation for business processes and the article provides useful insights into separating content based on context and need.

Rob...

[Geoff Evans]

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

[Edward K. Ream]

On Fri, Nov 8, 2019 at 5:34 AM Geoff Evans <gtev...@nl.rogers.com> wrote:

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?"

Leo's FAQ contains how-to's.  Feel free to suggest additions.

 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. 

Good idea.  This would be a useful addition both to the FAQ and to Leo's scripting miscellany.

I would like to delegate this task.  I understand the subject too well to put myself in a newbie's place.  I would be willing to help somebody who wants to improve the docs.

Edward

[Geoff Evans]

Okay, the basic question:  What is a very simple .leo file that will create a .ipynb file for a notebook with one markdown cell and one code cell that reports the outcome of some calculation?

I tried:

@file Note.ipynb

  @others

- - -title

       @language markdown

       ## Title

- - -calculation

        @language python

        x=4

        print(x+3)

but got something that didn't look like the format of other .ipynb files I have.

[Edward K. Ream]

On Sat, Nov 9, 2019 at 3:52 AM Geoff Evans <gtev...@nl.rogers.com> wrote:

Okay, the basic question:  What is a very simple .leo file that will create a .ipynb file for a notebook with one markdown cell and one code cell that reports the outcome of some calculation?

Leo doesn't provide that kind of support, and none is planned at present.

Leo's ipynb importer and corresponding writer allow limited round-tripping.  It's probably not all that useful.

You could define an abbreviation that would create an empty Jupyter notebook, but that would likely be of even less use.  Far better to create your notebooks in Jupyter.

Edward

[Geoff Evans]

Thanks Edward, that clears that up for me.  I still find it a bit odd that there was an announcement that Leo now supports jupyter, without any account of what the support consisted of and whom it might be useful for.

Leaving aside this specific example, I think my overall point about another component of documentation is still valid, even if I'm having trouble formulating it.  Maybe a better way to say it would be to break Tutorials into "for the committed" and "for the curious".  In the latter, experienced Leo people could be encouraged to write simple examples of "How this Leo feature helps me to accomplish the things I actually use a computer for."

Best,   geoff

[Matt Wilkie]

... to break Tutorials into "for the committed" and "for the curious".  In the latter, experienced Leo people could be encouraged to write simple examples of "How this Leo feature helps me to accomplish the things I actually use a computer for."

 

I like this formulation, especially the last sentence. I will bear it in mind for the things I write.

-matt