[Python-ideas] Off topic: 'strike a balance' - second language English

[Jonathan Fine]

Hi

Earlier today, I did a search for 'documentation by example python' and found

Example of great documentation in Python: Nick Loadholtes (copied)
https://ironboundsoftware.com/blog/2017/12/11/great-documentation-python/

The example is:
https://docs.python.org/3/library/random.html#examples-and-recipes

So who to thank: Here's the history of the source for the doc page.
https://github.com/python/cpython/commits/3.7/Doc/library/random.rst

I don't have time right now to look at all the history. But most of
the recent commits are from Raymond Hettinger.

I'll give Nick's web page the last word.

<conclusion>
Make your docs work as hard as your code does. Clear examples will
make your code stand out in a good way. Great documentation is out
there, lets make more of it. Here’s what you need to create:

* A plain language explanation of what your library does
* The shortest possible code example
* A quick list of any common issues
* Links to where you can learn more details

If you can create that for your code, you are doing a great service to us all.
</conclusion>

-- 
Jonathan