Allen HolubNov 12, 2022
Yes, but all documentation is technical debt. You constantly have to update it. It’s always wrong. Consequently, you should write as a little of it as possible.
---
RT @gurlcode
Poor documentation is technical debt.
https://twitter.com/gurlcode/status/1591157019075280896
Jenn Creighton on Twitter

“Poor documentation is technical debt.”

Twitter
Show threadTheDukeDKNov 12, 2022

@allenholub

What it is and does along with caveats is always nice.

Show threadAllen HolubNov 12, 2022
@TheDukeDK If you can guarantee that it's current and correct. Given that even Google can't do that, how well will the rest of us manage?
Show threadTheDukeDK

@allenholub

Mind, I am not talking detailed documentation here. I am all in for working code over documentation. #lean

More a simple statement of purpose and caveats, when they give value. That's generally not that hard to maintain and gives value to others.

Imagine Github full of repos with no readme in the root...

Nov 12, 2022 at 6:34pmWeb
Show threadAllen HolubNov 12, 2022
@TheDukeDK I'd do that by using TDD. The example/test is executable documentation, and you can use comments to explain intent. The only real issue is that it's difficult to put images into comments, but I've been happy with links for that.
Show threadTheDukeDKNov 12, 2022

@allenholub

If it software that you will never share, or is intrinsically understood by a small group of people. Then yeh, I can see that working.

Otherwise, expecting people to tediously go through comments to figure the purpose of a piece of software seems like an extreme to me.

Context matters, of course.

Show threadTheDukeDKNov 12, 2022

@allenholub

I have always felt that good documentation, not too much and not too little, is as much a skill as programming, creating good designs, architecture, etc.

Show threadAllen HolubNov 12, 2022
@TheDukeDK Yes, but I'd rather that the code was clear enough that it didn't need documenting. Also, I'm not talking about going through the comments. I'm talking about commenting the TDD example/tests, which are easily as searchable as a wiki or most electronic docs and are executable, so are guaranteed to be up-to-date and correct.