The Necessity of Documentation

Want to be more efficient? Spend time on Good Documentation.

Today I want to talk about a topic that is often disparaged within certain departments and industries: documentation.

Contrary to popular opinion, the more documentation that exists, the better it can be.

Typically, documentation is seen as a “necessary evil” that wastes time or resources when an employee could be spending that time on more “productive” projects or problems to solve. As someone who often learns by digging into software and messing around with settings rather than thoroughly reading a manual cover-to-cover, I can certainly empathize with this perspective, but there comes a point when the need for good documentation is absolutely critical for competent business functionality. After all, the time for creating an incident response plan is not after an incident has already occurred. Much like how risk management gives us a common language for business practices, good documentation of policies and procedures gives all parties a common understanding and expectation for the flow of events and order of operations.

The reason many see documentation as an annoyance is probably because it is incidental (or simply added to) an existing process. If anything, it’s often seen as that final step to get a project or ticket cleared and out of the way rather than as a crucial component of the process itself. Setting the standard of good documentation involves rethinking how we approach and solve business problems. If we consider creating and updating documents as part of the process from the very beginning, it will seem like less of a hassle.

Well, there are some very obvious reasons for documentation: software manuals for new users, knowledge-base articles for common troubleshooting problems, etc. However, for this article, I want to go a little bigger and talk about the need for documentation across the whole business.

First, as stated above, good documentation gives employees a common framework and understanding of behavioral expectations. It’s why HR departments develop administrative policies or a written code of conduct for workers. It’s also why we formulate response plans for incidents ahead of time — in the heat of the moment, it’s not guaranteed that someone won’t make some very obvious mistakes, so we document a list of best practices so that the right foundation is laid.

It’s also important for training. It’s helpful when a veteran can walk a new hire through a company’s normal procedures, but not every organization has that luxury. Those experienced employees might get called to an urgent matter, or schedule a vacation, or leave for a new job, or any number of other contingencies. By clearly documenting the procedures for any process (whether it’s simply resetting an employee password or installing a brand new server), it actually allows for experienced employees to focus their attention in meaningful ways, as they won’t have to worry about whether or not the right process is being followed (of course, check-ins are vital; adherence isn’t automatic). Additionally, if employees follow the same documentation for on-boarding and training, it guarantees that the right processes are being followed throughout the organization and that employees aren’t introducing their own individual quirks or grafting unsanctioned techniques onto systems.

Relatedly, good documentation is useful for project ownership, posterity, and efficiency. Think about what would happen if you had some sort of emergency and couldn’t finish a project. A company likely can’t just leave it in its unfinished state indefinitely — someone else will have to take over. Would they know what to do? While you may be safe from this scenario with regard to personal projects, this type of experience is almost guaranteed to happen in a company of any appreciable size. That’s why, when I’m training someone, I always emphasize that you should approach a project as if someone else may have to take over at some point. Have things been laid out sensibly? Can someone discern your process from what you leave behind or will they constantly call you back for clarification? These aren’t hypothetical questions. Whether you’re writing code, building a computer, or just responding to help tickets, at some point, project ownership changes happen. When it does, how are you setting up your team for success?

Finally, from a security perspective, documentation is one of the key ways a company can prove compliance. Compliance by businesses usually comes about through two primary avenues — either it is required of businesses through an external force (whether it be strictly required by government laws or more broadly encouraged via industry standards) or else a business has adopted its own internally enforced policies. In either case, a documented paper trail not only proves the existence of policies that meet these compliance standards, but it can also showcase ongoing efforts to improve compliance or meet new standards. Compliance, of course, is not just a checkbox to be completed and forgotten; such standards exist to limit or otherwise eliminate cyber risks on the part of the business or organization.

Documentation is so important that its existence or absence directly affects a business’s maturity. The CMMI Institute rates businesses according to the internationally recognized CMMI (Capability Maturity Model Integration) framework, which is designed to help businesses from a variety of industries grow in maturity by streamlining processes, maximizing productivity and efficiency, and decreasing risk across a variety of vectors. The higher the business rating in the CMMI model, the more proactive and less reactive that organization can be. An organization that only reacts and never proactively plans cannot expect to reach its goals. Crucially, a business cannot advance beyond level 2 of the CMMI model unless its processes and procedures are clearly documented, understood, and disseminated across the organization.

If creating detailed and comprehensive documentation doesn’t excite you, at the very least you should understand that it is essential for smooth and efficient workflow. And if you can’t find that enthusiasm within yourself, maybe reach out and find those who have that passion — they do exist. The sooner you can incorporate good, well-handled documentation in your day-to-day, the better off you and the security of your organization will be.

Further reading:

CMMI Maturity Levels —

How to Successfully Write ISO Documentation —

List of all the Common Cybersecurity Frameworks (Any mature framework will have documentation requirements, but what framework you adopt can be very industry and company-specific) —

Cybersecurity and Communication.