Hacker News Reader

Comment by pwdisswordfishc | Hacker News Reader

> "Just keep the documentation up-to-date" sounds about as practical as saying "just don't write bugs."

And that’s why nobody ever bothers with type checkers, code reviews, unit tests, CI and fuzzing in order to prevent, detect and fix bugs before shipping to production. You’re right, it’s totally impractical to apply any discipline to software development.

View on HN

The idea isn't "put no effort into keeping documentation up to date." It's to acknowledge that, in the real world, documentation does go out of date despite the best efforts of project maintainers. Sticking our fingers in our ears and saying "just keep it up to date then" is simply not a real position.

Despite a huge volume of tooling and methodology around reducing bugs, bugs still exist. This is a reality. One with associated costs and mitigations that we acknowledge. Likewise, the article is suggesting we acknowledge the reality that documentation does go out of date, even when effort is being put into maintaining it. That's why the point immediately preceding "It gets outdated" is "It requires maintenance" ;)

And that's what the post is about. To avoid writing bugs, you add type checkers, unit tests, DRY and other principles that you sometimes ignore (once you're experienced enough).

Clearly, you're talking about the same thing. TFA basically say 'to keep the documentation up to date, you need discipline, here's what I do'. Unironically, the 10th point I never thought about, and will immediately apply

Reply on news.ycombinator.com