[Doc-SIG] a better path from error message to solution
eiro at phear.org
Fri Dec 20 13:55:23 EST 2019
i try to educate my children to have a reasonable use of digital
ressources so they try to respect 2 rules:
* don't use a search engine if you don't need
* don't use the bandwith to get something you already have on
my kid use python at school and get stuck on very basic errors like
TypeError. I realize how difficult it is for a non programmer to make
the connexion between the error message and the relevant doc.
so: those are ideas i would like to share with your as a perl monger
who miss the perl ecosystem when writting python code:
* don't stacktrace by default: backtraces are just noise for newbies.
* make the messages a little bit informative. maybe with links to the
* have a python module that behaves like perl diagnostics (https://metacpan.org/pod/distribution/perl/lib/diagnostics.pm) at least as a ipython extension.
* make pydoc able to show the doc related to an Error
* make the official documentation available with man (the way perl does
it: man perl gives you the list of other man pages that are both
turorials and reference).
* have the error messages translated into natural langages
hope that helps.
More information about the Doc-SIG