Adam Dymitruk   Nov 13, 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."

👆 The worst take that keeps fueling #agile zealots.

This keeps pushing the "#code is documentation" racket. No, documentation needs to be there because it's the only thing that destroys the silos. Because we had a bad way to document doesn't mean we don't fix the core problem of making documentation effective.

Show threadezaquarii

@adymitruk Writing documentation is a great tool to discover bad design. So often "can't document it" runs alongside "spaghetti design". It is astonishing how many #bugs we discover just by writing #documentation and realizing that something simply doesn't make sense.

And it's not only end user documentation, but code and test scenarios (#bdd) as well.

Nov 13, 2022 at 6:29pmWeb
Show threadRod LecocqNov 13, 2022
@ezaquarii @adymitruk
Totally agree with that. I can't count the number of times I corrected / changed my design after documenting it and realizing it didn't make sense (even if everything worked, tests passed and everything was fine... well for now, probably not after a few, feature requests)
Show threadGhostGrrlSpyNov 14, 2022
@ezaquarii @adymitruk As a career tech writer (both end-user & developer facing) I can’t tell you the number of issues I’ve helped developers identify before they became major issues. Information developers are the first line of testing and make a point of doing things “wrong/illogically” because we know, somewhere, a user will. Writing clear, concise, useable, engaging, documentation is an art, just like coding is, that deserves more attention and appreciation. It isn’t easy.
Show threadAdam Dymitruk   Nov 14, 2022
@GhostGrrl007 @ezaquarii hopefully #EventModeling makes it easier