Re: Docs.
Forest through the trees; you can use `Ansible` or `Rocinante` to set up your system(s) but, you cannot take the Ansible play book and use it with Rocinante (or the other way around). Using those tools locks you into a system that may or may not break in the future (this is itself a dependency).
My tools are typically designed with "zero (aka: less) dependency" in mind -- double meaning, meaning: 1) little/no extra to install. 2) you can take the methods you create for use of my tool(s) to other tools (not dependent upon my tool).
While I obviously agree with you, that someone should document their program, sometimes just a program documentation isn't enough to see the "forest through the trees" (if you combine <lime> and <coconut>...) and I don't think a program's documentation should spell that out (beyond that program's actual use). But at the same time this is very much overlooked when someone is choosing the tool they will use. More often than not, they will choose the one with a fancy website or most github stars.
Re: Doc generators (code comments).
I cut my teeth on Lisp and SICP. I find it disconcerting that people have fallen into the trap of (self-documenting code). Self-documenting code is a stupid idea because IMO comments should be about "logic" and "why" not necessarily about "what". And they certainly shouldn't be omitted because you know the "XZY-pQ3 Algorithm better than everyone else".
Whilst, i++; //- increment 'i'. makes very little sense in the context of a program (or the ~25 lines you can see at a time), I'm guilty of doing something akin to this everywhere in my code; -e.g., i++; // eat the space. but my stance is: the point that i++ is meant to "eat the space", and future me is better equipped to say: "well, what happens if that's a comma, block-head?" and say if (*p == ' ') i++; instead.
If I come back to some code later, I very much appreciate my function headers (and often wish I wrote more) so, if I can make it easier on my future self by spending five more minutes typing a better comment, I will.
Real life story:
I saw some code a few months ago (and it was even in a lisp dialect, so I got to dust off some older skills). The code was maybe 30 lines but the whole write-up/code snips were basically talking about type safety (e.g. "3 + 4.0 = ?") and I found it amusing that I spent 30 minutes reading this code before I realised the whole blog write-up and sparsely commented code should have just been a coercion table with that written in a few function headers (-i.e. don't give me a "black-box" filled with crap and tell me it solves all my problems; when all it would really do is make debugging harder).
