Starting a Tech Business: A Practical Guide for Anyone Creating or Designing Applications or Software

Documentation

We Need to Write this Down?

Before I became accountable for an engineering team's performance, I considered documentation to be one of those dull managerial things you do when you can. However, once I became accountable for a team, I realized how documentation drove performance. When I looked at cases where the team developing a new feature had gone off in separate, noncomplementary directions, usually they had done it because they didn't understand the others' intent. As a manager, I had to ask myself how that had happened and how I could have prevented it. Documentation was usually a big part of the answer, partly because much of our team is distributed and we aren't able to have the frequent in-person interactions agile prescribes, though we have many chats going on Instant Messaging (IM). Engineers aren't the most talkative lot by nature, but most read documentation if they know where it is and what it's for. Plus, if your system is complex, it's impossible for everyone to talk to everyone else about every part of the system. Once we designed documentation into the development process earlier and with more structure, performance improved and not just in development. Operations and support had a much easier time delivering and supporting the product with customers.

One corollary to this is easier said than done. Most people hate doing documentation. After you get something working, you have a natural tendency to want to pop the cork and consider it done. Some engineers ...