"G. Branden Robinson" <g.branden.robin...@gmail.com> writes:
https://truss.works/blog/2016/12/9/man-splained
...
*sigh*
The good news is, I've never yet seen a man page that actually
mixed
man(7) and mdoc(7) calls in practice.
If i come across one, i'll let you know. :-)
I admit that that's not a complaint users of these conversion
source
languages seem to raise often. I suppose that this is for the
usual
reason that most programmers (and their managers) disdain
technical
writing. It's not "real work" and doesn't "deliver value"
... Approximately no one measures the cost of inadequate
documentation
to staff or the benefit of improving it
Yep. Years ago, i found the "Use the source, Luke!" refrain
amusing; now it just annoys me. The metamessage is: "If you're not
able to read and understand the source, you're beneath contempt."
Writing documentation is done by people too stupid to write
code. :-P
i'm increasingly feeling that lack of adequate documentation can
substantially contribute to people getting angry about shifts to
new systems/software. If the new thing doesn't have good
documentation, including specific information to guide people
through the transition, it's no wonder people will be resistant
and angry - they feel disempowered, and deprived of a sense of
control over their own system.
Just look at the uchardet library--it's been getting by without
any
API documentation for something like 15 years.
i'm sure "contributions are welcome" - you have nothing else on
your plate, so why not become familiar with the codebase and write
the documentation based on your understanding of how it all seems
to work? /snark
Alexis.
