The thing nobody wants to pay for - documentation

Posted Jan 29, 2024 15:23 UTC (Mon) by bferrell (subscriber, #624)
In reply to: The thing nobody wants to pay for - documentation by Wol
Parent article: The things nobody wants to pay for

If you think it's bad in FOSS... Proprietary software is MUCH worse:

"Documentation?! If you're competent, what do you need THAT for?"

The thing nobody wants to pay for - documentation

Posted Jan 30, 2024 17:30 UTC (Tue) by jezuch (subscriber, #52988) [Link] (1 responses)

Oh gods... I once worked for a big investment bank where the culture was that "the most powerful tool I have is the telephone" (said by the bank's CEO 50 years ago and mindlessly transferred to engineering, along with some more pieces of investment banking culture that don't make sense there). So if you wanted to know something, the expectarion was that you went for a chat with, or called a senior dev. The result was that there was next to zero documentation, maybe except some design docs, long out of date (because, as you well know, no plan survives contact with the enemy).

This. Was. Hell.

The thing nobody wants to pay for - documentation

Posted Feb 10, 2024 20:12 UTC (Sat) by sammythesnake (guest, #17693) [Link]

You're lucky you were working in the company that *wrote* the software. I have squicky cold sweats remembering being to fix software written by a previous contractor (our direct competition because we stole their maintenance contract) with no documentation of any kind (not even what the business wanted the software to do in the first place, let alone anything about how it was supposed to do it)

Really, what we need is for programming languages to work high enough level that "writing documentation" is a whole bunch less work because the programming language expresses not only what happens and how, but what's *supposed* to happen, and something of *why*. Unit tests/regression tests could also help a whole bunch on some of this by providing clarification of intended behaviour.

With the right expressiveness of programming languages and good unit/regression tests that refine the implicit "specification", clever automation could perhaps produce summaries from the code/tests - something vaguely akin to Javadoc etc. but *code* focused and able to summarise code (CodeGPT, maybe!)

With good languages/tools on this front, the amount of documentation that would need *manually* writing could be somewhat less and a much less daunting task - possibly less likely to be put off indefinitely(!)