Developers Hate Documentation

I've worked for companies of various sizes, from large enterprises to small startups, and my experience has been consistent: developers hate documentation.

You've just started a job at a company, and the tech lead sends you an onboarding guide. It was updated a year ago, which already seems odd. There appear to be some helpful links, so you click through a few of them. One is an RFC for a refactor that was done a few months ago, so you open that up. You find a few sentences of background, a diagram, and a bunch of links to code where changes will be made. You try to follow along as best you can, but you don't have the context for these changes. You go to the second link in the onboarding guide, which is a knowledge-sharing presentation done a year ago, when the service your team owns was first put into production. It provides some good background, but when you try to correlate some of the slides with the code, they don’t seem to match up. Exasperated, you go to the master branch in your repo and follow the README to run your team's service locally. It fails with a long, unintelligible stack trace, and you're still at square one.

You are tasked with implementing a new product feature. It's in a part of the product you haven't touched before, so when the button you're working on is clicked in the UI, you really have no idea what happens. You go to the wiki of the team that owns the area you're working on and find a few irrelevant links that are over two years old. I guess it's time to sift through code. You're a backend engineer, but you end up having to clone the frontend repo since GitHub search just isn't cutting it for you. After an hour of searching for strings you see in the UI, you finally find the API call to the backend. You trace the call through ten different services. You've finally figured it out, wrote up a technical design doc, and had it approved by senior engineers who looked through it for 30 seconds. You finish the implementation and test it out in your staging environment. You click the button, and nothing happens. Oops, looks like the state on the website is actually driven by another service that processes a Kafka event, so you'll need to update that too.

It's time to overhaul that service that your team seems to own. The service that has run reliably for years but whose code hasn't been touched in just as long. The service that, if it went down, would cause cascading failures, but it's somehow remained reliable. The engineers who worked on it have long left the company, and the service has been passed down to your team with no handoff or documentation. Your PM decides that they want a feature that would essentially require rearchitecting this service. You need to figure out every single caller of the service to ensure all flows will continue to work as intended. Time to sift through multiple codebases again to find all the callers. You feel like you've identified them and flip that feature flag to switch on the new and improved service in production. But oops, there's another legacy service that calls it using HTTP with JSON rather than Protobuf that you didn’t know about.

You think to yourself, "I'm going to solve this problem! We're going to do everything in Markdown because who doesn't love Markdown? After all, everyone hates Confluence, so there's no chance that's going to work. Embed code in Google Docs using the janky Code Blocks plugin? No way." You get all the other teams on board, even offering to create diagrams since you're well versed in the architecture. A year later, all the diagrams are outdated and you're back at square zero.

P.S.
We're trying to solve this problem for all developers, check us out here