4 ms·
The problem is that this sort of documentation is often incorrect, incomplete, or out of date, so people learn not to trust it.
by jstanley 3y ago
The problem is that this sort of documentation is often incorrect, incomplete, or out of date, so people learn not to trust it.
- tivert 3y ago> 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.
- hm-nah 3y ago> The problem is… …multifaceted from my experience. 1. At the org-level… - 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!
- EMCymatics 3y agoThe worst environment is when people don't bother to update documentation. That's when you know you have a garbage shop.