Re: Guide to writing better software documentation

[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

-- 
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 view this discussion on the web visit 
https://groups.google.com/d/msgid/leo-editor/9393bcf8-4d90-41d0-b14f-8b52780790ae%40googlegroups.com.

Re: Guide to writing better software documentation

[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

On Saturday, 9 November 2019 07:30:27 UTC-3:30, Edward K. Ream wrote:
>
> On Sat, Nov 9, 2019 at 3:52 AM Geoff Evans  > 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
>

-- 
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 view this discussion on the web visit 
https://groups.google.com/d/msgid/leo-editor/226f516c-5c46-4069-8a40-db081a641aa7%40googlegroups.com.

Re: Guide to writing better software documentation

[Edward K. Ream]

On Sat, Nov 9, 2019 at 3:52 AM Geoff Evans  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

-- 
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 view this discussion on the web visit 
https://groups.google.com/d/msgid/leo-editor/CAMF8tS34S%3D7UvPPL0Rq-yOZh3KGWdrA8p3mA5rhQ5ut6s46uDw%40mail.gmail.com.

Re: Guide to writing better software documentation

[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.

On Friday, 8 November 2019 09:38:40 UTC-3:30, Edward K. Ream wrote:
>
>
>
>  
>
>> 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.
>
>

-- 
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 view this discussion on the web visit 
https://groups.google.com/d/msgid/leo-editor/d17969d3-e06e-41bf-839b-1fdfe5ba530b%40googlegroups.com.

Re: Guide to writing better software documentation

[Edward K. Ream]

On Fri, Nov 8, 2019 at 5:34 AM Geoff Evans  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

-- 
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 view this discussion on the web visit 
https://groups.google.com/d/msgid/leo-editor/CAMF8tS2k3ef%3DGwvM9-dcs7PRrq-n_wENwG3Xfec1sMuo5RBYFg%40mail.gmail.com.

Re: Guide to writing better software documentation

[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

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 leo-editor+unsubscr...@googlegroups.com.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/leo-editor/31426ca4-7f52-4b6d-9ad0-8fd7d82be57c%40googlegroups.com.

Re: Guide to writing better software documentation

[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...

-- 
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 view this discussion on the web visit 
https://groups.google.com/d/msgid/leo-editor/d795b795-659b-4800-a121-e95607faaad0%40googlegroups.com.

Re: Guide to writing better software documentation

[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...

-- 
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 view this discussion on the web visit 
https://groups.google.com/d/msgid/leo-editor/1b889060-a78b-4fb7-aa50-2f856eff91a7%40googlegroups.com.

Re: Guide to writing better software documentation

[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...

-- 
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 view this discussion on the web visit 
https://groups.google.com/d/msgid/leo-editor/8080847e-aaa9-40f7-b264-c9c6aeac2c46%40googlegroups.com.

Re: Guide to writing better software documentation

[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

-- 
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 view this discussion on the web visit 
https://groups.google.com/d/msgid/leo-editor/763f776d-141b-49b4-9c39-8d443af7ce9d%40googlegroups.com.

Re: Guide to writing better software documentation

[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

-- 
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 view this discussion on the web visit 
https://groups.google.com/d/msgid/leo-editor/d0d081cb-5107-4981-baf0-306a5b4bbd29%40googlegroups.com.

Re: Guide to writing better software documentation

[Edward K. Ream]

On Sat, Oct 26, 2019 at 4:36 PM Matt Wilkie  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

-- 
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 view this discussion on the web visit 
https://groups.google.com/d/msgid/leo-editor/CAMF8tS1Bf%3DLon2kLQA1%3DO0SXgvmE3xdOjT1FtkubHVvzajr%2B0Q%40mail.gmail.com.

Re: Guide to writing better software documentation

[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

On 28/10/19 8:00 a. m., rengel wrote:
> On Saturday, October 26, 2019 at 11:35:57 PM UTC+2, 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
>
>
> 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
> -- 
> 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 view this discussion on the web visit
> https://groups.google.com/d/msgid/leo-editor/f3537245-369b-494e-94e2-3df43296b2d1%40googlegroups.com
> .

-- 
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 view this discussion on the web visit 
https://groups.google.com/d/msgid/leo-editor/31a06fbe-4719-4c0b-db0c-d802c991e438%40riseup.net.

Re: Guide to writing better software documentation

[rengel]

On Saturday, October 26, 2019 at 11:35:57 PM UTC+2, 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
>

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

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