Hacker News Reader

Comment by CipherThrowaway | Hacker News Reader

Which specific points in the post did you disagree with? "Just keep the documentation up-to-date" sounds about as practical as saying "just don't write bugs."

The impact and importance of documentation varies from project to project, but it is hard to see these hard-line takes on the importance of documentation as anything more than grandstanding. In the real world, where consumers and businesses exchange money for goods and services, and where organizations, individuals and teams must wrestle with market conditions, deadlines, KPIs and so on, documentation is a supporting act.

View on HN

> "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.

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

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" ;)

Honestly out-of-date documentation is most often better than no documentation at all

Reply on news.ycombinator.com