[Doc-SIG] a better path from error message to solution

Marc Chantreux eiro at phear.org
Fri Dec 20 13:55:23 EST 2019

hello people,

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
  your machine

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 mailing list