> The problem is that this sort of documentation is often incorrect, incomplete, or out of date, so people learn not to trust it.
That's not a problem with the documentation, it's a problem with those people's attitude.
I find "incorrect, incomplete, or out of date" documentation extremely valuable. Documentation is always just one data point in a constellation of data points needed to understand something, but it can often fill in important gaps that can't be filled in any other way. Not having it always leaves you off in a worse situation.
- no standard doc tooling
- no easy-to-remember URLs
- no simple permalinks
- no easy-to-update “pages” (AKA markdown-based)
- they certainly don't train employees how to create good docs
- minimal if any doc standards
2. At the leadership-level…
- they don’t incentivize good documentation
- they don’t set the expectation that “everybody writes”
- they don’t document themselves!
It’s no wonder docs are scattered, out of date and untrustworthy!
That's not a problem with the documentation, it's a problem with those people's attitude.
I find "incorrect, incomplete, or out of date" documentation extremely valuable. Documentation is always just one data point in a constellation of data points needed to understand something, but it can often fill in important gaps that can't be filled in any other way. Not having it always leaves you off in a worse situation.