Programming

Hard disagree that documentation is a waste of time. I think you’re just failing to see and use documentation correctly.

Tech documentation should never:

• record implementation details; that’s what commits and PRs are for
• be about the code, but about the solution, information, or provide guidance; use code comments when talking about code
• be taken as 100% accurate or infallible, but the general direction or essence should still remain true (related to the 2nd point)
• be expected to be up-to-date; readers should always look at the created / completed / last edited date and make a judgement how much salt to actually take from it

Documentation can

• be some kind of paper trail that shows how we got to where we are
• provide guidelines for getting started on a project, or some part of a larger project, with more context with respect to the business, so that readers are equipped with sufficient context when diving into the code (READMEs can then just focus on setup and testing instructions)
• go further into what goes around a solution, eg considered alternatives, what actually requires solving given a functional requirement (it’s not always the case that we can fit a solution within a sufficiently small ticket, so tickets might be too localized to give a bigger picture of how a problem is being solved)
• record system architecture, with actual illustrations, which can be easier to grok than 50 Terraform files

Writing these out is also good for people who don’t read code or don’t have the time to read code, eg your tech lead, your manager, Tech VP, etc, people who should have some idea of your system or solution, but not necessarily the implementation detail, so that they can do their work more effectively.

There’s also a culture where a project, or a sufficiently complex problem, starts with a tech proposal, which would properly capture the problem and do solution planning. It’s easier and faster to change than a PR, and reviewers can read that for context. In any case, this democratizes knowledge, instead of creating more tribal knowledge.