Your documentation will be read by almost nobody. Write it anyway.

Documentation is a chore that IT professionals hate doing. For most of us, it’s right up there with picking staples out of the carpet or scrubbing the tile around the toilet in your home. If you’re nodding in agreement right now, may I humbly suggest a different perspective?

Documentation can provide some substantial benefits, but you will probably have to adjust your ideas about how and when to create it to realize those benefits. Let’s talk about some of the reasons, spoken and unspoken, that we don’t ever seem to find the time to document.

“I am a senior engineer. It’s not a good use of the company’s opex to have me doing something a technical writer or junior engineer should be doing.”

The more “senior” you are, the more your documentation has the potential to positively influence your organization. A Network design engineer, for example, will often find flaws in his design while he is drawing diagrams that explain the solution he is building. This has certainly been the case with me whenever I have worked in that role. This implies, then, that the time to document is not after the design work is done, but rather, during the design effort. How cool would it be to find your problems and mistakes before you present budget numbers to your management or customer, rather than after? If you’ve ever felt the pit in your stomach when you realize that you’ve forgotten a license or goofed up the math on the number of boxes, you know what I’m talking about.

Also, it is highly unlikely that a technical writer or junior engineer can put together documentation with anywhere near the efficiency that you can. Perhaps you are insecure about your ability to effectively communicate in writing what is in your head. Maybe the hundreds of buttons and knobs in Visio turn what should be a 5 minute task into a 2 hour ordeal for you. Whatever your hangup is, it is well worth it to you and your career to figure out how to overcome those things.

“The network is the documentation”

I have some sympathy for this point of view, because a well-designed and well-implemented network will be configured consistently. Someone who truly understands the protocols and the interoperation of them can look at the configuration of a couple of devices and pretty well predict what the original designer’s objectives were.

This ideal network exists almost nowhere, however. Networks experience configuration “decay” or “drift” over time, which happens for a variety of reasons. There is a critical shortage of networking professionals who actually understand networking at a fundamental level, so it is unlikely (statistically speaking) that your organization employs very many of them. Good docs can be the thing that makes it possible for a less experienced engineer to succeed in their assigned tasks. Good docs can help an experienced and truly senior engineer cut past hours of trying to read your mind and actually accomplish a complex change or troubleshoot a difficult problem.

If you are working in one of the rare shops that has embraced DevOps and the principles of CI/CD in their network infrastructure, the documentation is even more important to you, because it lays the foundations for the code that will have to be written to bring your solution to life.

“I don’t have time to write docs”

This argument is the first cousin of the much-maligned and super-lame “I don’t have time to automate”.  Good documentation allows an implementation engineer to successfully implement something that you designed without having to redo all of the mental gymnastics that you went through to come up with the design, and this is a good thing. If you wear both hats, then good docs help you quickly get back to that mental zone you were in when you created the design. Humans forget things at an alarming rate, and you are likely not immune to the forgetting.

If your team is large, or if the rate of change in your network infrastructure is high, you can accomplish impressive economies of scale with good docs. Without good docs, engineers will continue to run like hamsters on a wheel, continually re-doing the same work over and over and over again. If the success of other engineers matters to you, (and it should if you have any vision about where our industry is headed) then you will see that your time is well spent writing good documentation.

“If the other engineers were smart enough, they wouldn’t need me to babysit them with a diagram or wall of text about how networking works – they should be able to figure it out on their own.”

This kind of statement is usually born of hubris. An engineer who says or thinks this is likely deluded about their own awesomeness, and is quick to talk down to or about other “less awesome” engineers. If this is you, I strongly urge you to reconsider your position. You never know which of those junior engineers has had it with your treatment of them and is working their tail off at night and on the weekends, while you’re relaxing, to catch up with you. When they do catch you (and it will come faster than you think), you will end up leaning on your position of authority instead of your expertise, and you’ll lose credibility.

A much better course would be to learn some humility and write down your thoughts and reasoning, and maybe even draw a few diagrams, in the spirit of helping the junior guys along. You may end up with an ally who is committed to, and proficient at, doing all of the tasks you don’t want to do, and everyone will win.

“If I document the design of the network, I’m giving away the secret sauce. People will use it against me. Or worse, I will lose my relevance and be seen by management as not vital to their success.”

It’s true that documentation can be used for political purposes, sometimes even at multiple levels of management above you. I have personally experienced having my docs used in this way – but it has never hurt me.

Some engineers fear that their manager will see them as a replaceable cog in the machine if they document what they’re doing. Or they think that if nobody has to come to them personally for their wisdom about how to build or fix the network, they will lose power and influence. My experience is the opposite. Having my name on the docs has always given me more influence, not less. I’ve had good managers and bad managers, but I’ve never had a manager that tried to manage me out or give me less interesting work because I shared my knowledge with my peers. In the end, the things that make up our experience and expertise can’t be distilled down into a document – but the explanation of our designs can be, and should be.

Documentation does not make you replaceable – it makes the work that you do consumable. If it’s easily consumable, it’ll very quickly become the standard that everyone uses.






Leave a Reply

Your email address will not be published. Required fields are marked *