Imagine a manufacturer who starts up a production line knowing that each time a worker reached a certain point in the process she or he would have to walk over to the foreman and ask for a critical piece of raw material. Naturally no company would ever do such a thing and if it did it wouldn’t be around for very long. This process would cripple productivity, dramatically increase the cost to produce each piece and send the time to market through the roof. The company would fail and we’d all agree that with a workflow like that it probably deserved to.
Despite that opinion, we in software development seem to think it’s OK to function under the same asinine workflow. Don’t believe me? Has your team or company ever had to…
- …delay a deployment
- …rejigger the development schedule
- …miss a deadline
- …lose a customer
- …call someone in the middle of the night
…deal with under-trained staff </ul> …because the only person with the knowledge is somehow unavailable?
In our field of software development we’re justifiably proud of the fact that we make things. We take a jumble of arcane symbols and arrange and assemble them in such a fashion that the end product improves someone’s life in some way. We manufacture tools and toys to fill needs for our customers. Software is our product and programming is our production line. Like any production line we need a stockpile of raw materials. Knowledge is ours, but I’ve yet to see a software team or company which doesn’t fit the ludicrous example I presented above. Each one has at least one person on the team who’s been there forever and knows the entire product inside and out, idiosyncracies and all. Each one has a resistence toward documenting this knowledge, making the raw materials available to everyone on the production line. And each one pays a terrible price in productivity and scalability.
This isn’t the way things have to be. This is the way we allow them to be. We have it within our power to fix this problem and all it takes is documentation and sharing of information.
When asked why a process or fact isn’t documented most teams will answer, “We just don’t have the time.” While, yes, it does take time to write these things up it takes considerably less than the time that’s lost when people are searching for answers. The lack of time is just a convenient cover for the real reasons things don’t get documented:
- People don’t understand the value of documentation. We need studies showing how much time and money is wasted chasing down undocumented answers. I’ve little doubt that managers would be aghast at the resources they’re flushing down the loo. Once the managers understand the value they can start communicating it to their departments and making knowledge documentation a priority for everyone on the team. This sort of thing has been done before in our industry. Years ago no one had time to write test suites for their code. Eventually people grew to recognize how invaluable a robust test suite is to a product and started including them in the software development process. The same thing needs to happen for capturing knowledge.
- Writing docs isn’t as fun as the other parts of the job. Let’s face the facts: the team would much rather be running the processes than writing about them. Tell folks to write something up in the wiki and they’ll drag their feet and come up with every excuse in the book to avoid it. For most people it’s just not fun. Ya know what else isn’t fun? Getting woken up in the middle of the night because you’re the only one who knows how to restart the webapp properly. Taking a couple hours out on a Friday afternoon to write up tips and instructions on a mission-critical procedure can be a good way to wind down toward the weekend and can help reduce immense amounts of stress later on when someone needs that information.
- People want to feel important. You’re it. You’re the one. You know every line of code, every method call, every peculiarity of server setup, every script or tool and all of their undocumented uses and command line options. You are the Most Important Person in the Company. Capturing all that you know and sharing it with everyone would be best for the team but—so you believe—it would drastically reduce your power and influence at the office. Here’s the truth of the matter: You’re a bully and no one really likes you very much. You’re holding your team hostage and they’re right to start resenting it. What you need to recognize is that what makes you important and influential at your job isn’t the knowledge you’ve amassed but the fact that you have the ability to amass it in the first place. Documenting and sharing that knowledge with the team isn’t going to reduce the amount of knowledge; it’s going to free up the time you used to spend answering questions so you can learn and create even more knowledge. It starts a cycle of knowledge generation with you at the center. Congratulations: not only have you made yourself even more important but now people like you. A lot.
There are some ways that managers can help reduce knowledge hoarding on their teams. The first thing they can do is start asking the team to include documentation in their time estimates. This helps show that brain dumps are as much of a priority as test suites. It also removes the excuse of not having the time to write up processes and procedures.
Another thing that can help is including documentation in the build process. If no documentation is found, the build should fail.
Also, managers can and should reward team members who make contributions to the internal documentation. Have a doc-a-thon. Hand out prizes. Do whatever you need to do to show the team that documenting processes and procedures is valued by your organization.
This isn’t something that you’ll be able to do overnight. It’ll take infrastructure, time and commitment. Undoubtedly you’ll fail and have to start again. Maybe more than once. But when you hire someone new and she’s able to hit the ground running and be productive in less than a week because she was able to find her answers in the wiki then you’ll know that all the effort was well spent.