At 2024-10-26T13:33:02+1100, Alexis wrote: > > 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. :-)
Thanks! Could be fun to have another opportunity (via the macro package "unloading" I proposed) to exercise my status as "god-king of groff".[1] > > 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 Yes. I'll point out a major vector of that corrosive attitude (and many others). http://www.catb.org/jargon/html/online-preface.html > 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. I entirely agree. > > 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 I have in fact considered it, thanks to a frustrating situation with uchardet and Homebrew.[2] Will I get enough round tuits before someone else does? Who knows? Regards, Branden [1] ...which I somehow acquired without even yet being maintainer! https://lists.gnu.org/archive/html/bug-groff/2024-01/msg00008.html [2] https://savannah.gnu.org/bugs/?66143
signature.asc
Description: PGP signature
