CAUTION: CONTENTS ARE HOT! Why We Write Documentation Without The Assumption of Knowledge

Imagine walking into a gas station and grabbing a coffee from one of those self-serve dispensers. You will likely see a sign warning, “Caution, contents are HOT!” Seems like common sense, right? Perhaps if you’re familiar with these types of dispensers, it would be. But we all know the reason these types of cautionary signs exist – because for someone else, for whatever reason, it wasn’t obvious.  

We need to apply this same level of clarity when it comes to security documentation meant for non-security people. What might be obvious to us, will not be obvious to everyone. What we are familiar with, not everyone will have the same experience and knowledge.  

The world we live in today is rife with cyber threats, and a single human mistake could open the door to an attacker. Generally, these mistakes are not intentional or malicious; they come from a lack of experience or clarity on what to do. So how do we address this? While it may seem excessive to simplify things to this level, the reality is any security controls that require some level of user interaction need to be explained in this manner. 

One of the most critical aspects of security documentation that is often overlooked as policies, standards, and guidelines are developed - ensuring they are tailored to the intended audience. Often, this documentation is written from the perspective of security, legal, compliance and privacy teams, NOT for those that must interpret and act upon them, creating gaps in security as users struggle with compliance while still being able to get their jobs done. 

Build Employee Trust

Communication is a cornerstone of building trust, and you must have employee trust in order to have an effective security program. When security becomes a blocker to productivity, users lose trust or are unable to build trust with Security Teams. Making things easy to accomplish and easy to understand not only builds trust among employees but also creates a more secure environment by enabling non-security professionals to follow security guidance and best practices in a frictionless way, trusting that they can still accomplish their work and do so securely. Clear documentation helps demystify security processes, making them more approachable and less intimidating. 

Trust is the foundation of any successful organization. When security teams take the time to understand their audience and write documentation that is clear, concise, and relevant to the audience, it shows that they are enablers, rather than blockers to productivity. This builds trust and encourages employees to engage with and comply with security protocols.  

Make It Easily Discoverable And Clear

Not everyone in an organization is a security expert, and that’s okay. However, everyone plays a role in maintaining security. By creating documentation that is easy to understand and follow, security teams empower non-security professionals to contribute to the organization’s security posture. This includes using plain language, avoiding jargon, and providing step-by-step instructions that anyone can follow.

Documentation is also only useful if it can be easily found and understood. Ensuring that security processes and guidelines are discoverable means organizing them in a way that makes sense and is accessible to all employees. This might involve using an internal wiki, a well-organized document repository, or even regular training sessions to highlight where key documents can be found. Clarity in documentation means using straightforward and standardized language as well as clear formatting to make information easy to digest.

Keep It Fresh

The cybersecurity landscape is constantly evolving, and so should your documentation. Regularly updating security documents ensures that they remain relevant and effective. This prevents information from becoming stale or outdated, which can lead to security gaps. Establishing a routine review process for all security documentation can help keep everything current and accurate. Additionally, some things, such as security policies, need to be reviewed and approved at least annually for industry standard security audits and certifications. e.g. SOC 2, ISO 27001, HITRUST, etc.  

 Final Thoughts...

Writing security documentation with the audience in mind is not just a best practice—it’s a necessity. There is a human component to all security programs. To build an effective security program requires building trust, enabling non-security professionals to easily remain in compliance while still accomplishing their work, ensuring discoverability and clarity, and keeping information up to date. By adhering to these principles, security teams can create a more secure and cohesive environment.  

Remember, effective security documentation is a cornerstone of a resilient organization. 

Until next time...