Imagine working on a team of programmers who write perfect code, never forget anything, never leave the team, have perfect verbal communication skills, and love meetings. That would be weird on many levels, but at least then you’d have a chance of not needing any technical documentation. The rest of us, who have legacy code to deal with, need to know how to write useful documentation. Otherwise, other peoples’ code will become a single point of failure to understand what’s going on.
Technical documentation is our backup for not being able to understand a system and its code by looking at it. Unfortunately, these backups probably haven’t been tested recently and don’t actually work. The solution is to write less documentation, not more, but also not none. By writing less documentation, you can focus on writing documentation that counts, actually maintaining what you write, and have more time left over for writing code.
- C++ Europe Conference - 25 February 2020