When to write documentation

Improve the speed of your development team

It’s probably fair to say that no software engineering team ever has the right amount of documentation on the code they write. Documentation here I’m defining as the write-up that is done after a project ships to explain how the technical systems work. But over the years, I’ve come to get some heuristics to feel if my team is either spending too much time writing docs, wasting potential engineering cycles, or too little, leading to miscommunication and slow ramp-up times. Here they are, in order:

Is your team, including any other cross functional partners, fewer than 5 engineers? If so, don’t bother writing docs. On a small team, you should just schedule a meeting with the person who wrote the code originally. It might be tempting to think, “Our code is so complicated and needs to be explained!” But the time you spend polishing the wording, drafting diagrams, and soliciting feedback on documentation is time that could be spent tightening the code itself. In the end, you’ll always need to have that in person meeting anyway to answer questions.

Is your team greater than 5 engineers, or have a lot of adjacent teams? In the larger organizations I’ve developed in, documentation on neighboring team’s subsystems were a lifesaver. They allowed me to quickly ascertain whether a particular solution was going to fit my usecase in a self-serve manner, no time wasted. If your team interacts with a lot of other teams, it makes sense to spend the time polishing the docs, as they can be an excellent reference for them without wasting your time on meetings.

Is someone going to leave the team soon? If so, make sure they write documentation before they leave, or else risk losing the inside knowledge. At the very least, have a meeting talking about the systems they built, and record the conversation.

Is someone going to join the team soon? In this case, don’t bother writing technical docs. This may be controversial, but the more time you spend face-to-face with a new engineer during their ramp-up, the better. Rather than writing up a doc for them to read, schedule meetings where you can walk over the code in relevant chunks. This allows them to ask questions as they go along, and also starts to build the working relationship that you’ll need in the future.

This synchronous ramp-up style also avoids the major pitfall with new-hire documentation: incorrect assumptions from outdated documentation. Once when I was onboarding to a new codebase, I incorrectly assumed how the service worked by reading outdated documentation. It wasn’t until after I had already started down the wrong path that I met with the stakeholders, and could be steered correctly.

In Conclusion

Writing documentation is expensive, both in the initial drafting phase and the continued maintenance. If your team is small, skip the documentation and get to work on the code itself.