Discussion about this post

User's avatar
Carl Youngblood's avatar

While you do provide some noteworthy examples, I fail to see how they would not have been avoided by simply keeping all process docs in some kind of revision control system and making sure they were updated with each new discovery. They seem like fairly straightforward cases of failure to update the documentation. RCSes make this even easier nowadays.

When I manage teams, we create a "definition of done" and make sure that no deliverables are considered complete unless each item has been checked off. A common item on the checklist is "Documentation has been updated for any relevant changes in software behavior or expectations." Other common items would be "Any publicly-consumed APIs have been documented, with common usage examples," and "All important non-obvious architectural decisions have been well-documented with comments."

Something as basic as a missing ingredient in a recipe would be a catastrophic documentation failure.

Expand full comment
Micheál Reilly's avatar

Really recommend the book "The Shock of the Old" some great examples of forgotten tech but also long this line of forgetting, there is also the persistence of many old technologies, far beyond their narrative expiry.

https://en.wikipedia.org/wiki/The_Shock_of_the_Old

Expand full comment
7 more comments...

No posts