XD blog

blog page

documentation, python


2019-06-27 Documentation needs work

A bug. One more. I read the documentation of the fonction. It hardly describes what it does. This long paragraph is probably clear for its author but still kind of obscur to me. When i understand it, it tells me that what i wrote is partially wrong but i wrote so many lines that I'm puzzled about which is wrong and which is right. So what... i go on github to see where this exception may have been raised and then i realize this information i need is not there unless i expand the error message with what i need. But then i'll to recompile and that cost 30 minutes on my poor ugly laptop. So what... I skip it unable to convince myself to freeze my machine for that much of time and drink coffee for half an hour which is much more than the small quantity that would keep me awake for ever. So i tried poking with parameter almost randomly - what i kindly oppose when my students do it - to find out the combination which works out of the many combinations Hermione - I'm pretty sure - would have been happy to solve. And finally when i find, all seem logical in a way i kindly disagree with all the non informative error messages i got all along doing it...

I need to be drunk before this fully uninteresting task gets up to my brain, before this part of my body realizes whatever i do practice is always what I need not to feel the pain of struggling against such nonsense, before it realizes that coding is one among the few kinds of shared art, something people may do with other people just because they never get somebody to tell them it was so beautiful that it deserves to be hanged on their wall.

Whatever, I'm still at that bug, skipping the documentation which does not make sense to me tonight and directly going to what causes my picasso face, a kind of disorganized puzzled face. Anyway, I'm in the CODE, the open source code and I feel happier just because the code is precise and is not outdated. Writing documentation reminds me the summary exercise I did in the preparatory school to Grandes Ecoles. A good documentation takes time. Otherwise, a link to the code is just what i need.


<-- -->

Xavier Dupré