Don't Get Caught in the Dark: How to Build Better Documentation for Security Teams

Most security professionals will agree that detailed technical documentation is essential for effective communication and long-term consistency. However, writing documentation is often viewed as a chore that steals time away from higher priority tasks. Documentation is the glue that binds together the workflow of highly technical security teams, supporting high-stake customer deliverables and tight deadlines. Therefore, it is important to prioritize building fast, straightforward, and efficient habits around writing documentation.

No matter how you use documentation within cybersecurity, this blog will offer tips to simplify the process so that your documentation can be shared time and time again. Follow our user flow guidelines and use them as a checklist to cover all your bases when writing up your hacking adventures. For a deep dive into technical writing elements of cybersecurity and popular acronyms in the industry, we recommend downloading our popular Cybersecurity Style Guide.

Getting Started

To start, we suggest getting into the habit of logging your hacking content as notes because these will become the foundation for the documentation process. Notetaking from beginning to end of a project is a good habit for you to incorporate into your daily routines. Taking notes throughout the process allows you to capture important details and ensure that any undocumented features or “gotchas” are accounted for. Otherwise, users will be forced to hunt down other resources to get the full picture further down the line and this can lead to frustration and turn into a time sink.

There is not a specific recommended format for taking notes; however, be prepared to capture as many details as possible as this will help in the long run. Jot down every action taken; copy over helpful URLs and code blocks; rationale regarding why you may have chosen a particular method over another, and links you visited for additional information. Log all of it!

It is equally important to consider where you log your notes because an effective notetaking system is an important base for the entire process and will set you up for success. If you aren’t already using Markdown, we recommend trying it out as an easy way to catalog your hacking notes. To get more bang for your buck, use it with VSCode for on-the-fly dynamic, rendered previews. Check out this example of a Markdown template to give you a leg up and start organizing your security trials and tribulations . These are great options to start creating efficient documentation that can be used individually or across a whole team. With this three-step setup – one to hack, one to organize your hacking notes in Markdown, and another to render those notes in VSCode – you are well on your way to creating detailed and impactful documentation.

Defining User Flow

Once you have finished collecting your content, you should investigate ways to make it quick and logical to consume. The user flow is the navigation path the reader takes to find what they need as quickly as possible. Don’t worry about which software solution your team is already using for digital storage and organization (i.e. Docsify, ReadTheDocs, MkDocs, GitHub/GitLab, or Atlassian), because Markdown easily renders in most solutions. Instead, concentrate on a repeatable and dependable user flow in your documentation to guide the audience. A user’s eye will often scan over content causing them to miss crucial information.

The case for a strong user flow is supported by a multi-part study conducted by the research-based user experience (UX) group Nielsen Norman Group in which 500 participants were evaluated in over 750 hours of data eye-tracking to analyze how they read digital content. The study found that after approximately 25 years, content consumption habits have changed very little, and moreover, the study found that “people still primarily scan, rather than read. Scanning all of the text on a page, or even a majority, is still extremely rare. Even when users do scan content in its entirety, they never scan it perfectly linearly.”

There are a variety of scanning patterns that users employ based on the content with which they are presented. However, with text-heavy documentation, as is common in cybersecurity teams, the most frequent method that readers use is known as the F-shaped scanning pattern. This pattern is where a user scans content from left to right, top to bottom, with an emphasis on the first few words, when they are presented with large, mostly unformatted blocks of text.

Luckily, using options like Markdown for documentation mitigates some of the scanning burden with templates and standardized language so that readers know what to expect and know where to find what they are looking for. This helps in the same way that beautifying source code aids with readability and speed instead of trying to digest it as a single blurb.

Build a Dependable User Flow to Guide Users

Armed with the knowledge that readers will default to scanning the content quickly, we can build our documentation in a way that more effectively guides them to the information they are looking for.

We have set out some guidelines for content creation that will help to build a user flow for your readers. This way, they will know what to expect and how to navigate to find the information they need. We suggest the following techniques:

• Create the outline first with an emphasis on readability:
  • Short sentences of 20-30 words (if you run out of breath, it’s too long).
  • Use active voice and verbs where possible (e.g., The team found 20 vulnerabilities vs. 20 vulnerabilities were found).

• Write with structure:
  • Make sure bullet points can stand alone as single ideas or instructions.
  • Use a hierarchy with heading sizes to distinguish between major sections and minor ones.
  • Use a table of contents that link to each of the header sections.

• Prioritize the important stuff, and be direct:
  • Keep headlines descriptive and related to tasks the user will be trying to accomplish.
  • Instead of ‘there is an X that can be used to accomplish Y’, use ‘to accomplish Y, use X’. This might feel cold and uninviting, but remember users are scanning for answers. They are searching for the cooking instructions, not the family story behind the recipe.
  • Remember, these are documents to help others get things done – give them the steps to accomplish the task.

• Use examples:
  • Examples help users to understand how they can use the information being presented in their own circumstance and what they can expect at each step.
  • Code blocks, especially when set to the correct language type, are a terrific way to present examples.
  • For less technical topics, avoid relying solely on embedded images as part of the instruction. These are great as visual aids and methods to orient the user, but images inhibit content indexing and search functions. Be sure to write out the steps referenced in the image, as this helps with accessibility by providing alternate text to the images included.

• Use Global English:
  • Global English is a precise, logical and literal way of writing that makes it easier for non-native English speakers to understand written English.
  • Get the message across clearly by:
    • Sticking to the indicative or imperative mood (facts or instructions) and not the subjunctive (wishing, believing, suggesting, insisting).
    • Avoid jargon, colloquialisms, undefined acronyms, contractions, and abbreviations.
    • Avoid using ambiguous pronouns, and instead try to be as specific as possible. Instead of “those” or “for each of them”, use “for each line item in your list.”
      

Staying Up to Date

The last part of your documentation journey is planning how to keep the information up to date. So, who is responsible for making sure these newly minted docs don’t go stale? On the Cosmos team, we have adopted a ‘see something, update something’ strategy within our team to eliminate single points of failure in the documentation process. This ensures the entire team has experience with drafting and recording operational procedures, which also aids us in documenting institutional knowledge that may not be apparent to everyone on the team.

As the Cosmos service continues to grow, we are testing new approaches to documentation and guidance maintenance to find what works best for us as new team members continue to join the service. Lately, we have been tackling the following areas:

• Ensuring that conventions in our operational procedures, codebases, and tooling all have clear rules of engagement and are clearly understood;
• Creating (and clearly communicating) contribution guidelines and coding best practices;
• Verifying that all projects contain a README (keeps documentation in the code repository, which helps streamline updates);
• Verifying that any blockers are submitted as a ticket or issue;
• Creating states in our work pipelines that alert on codebase changes and updates, and alert team members to quality assurance updates;
• Using update schedules and release notes to ensure the team is synced on feature revisions and new best practices, and
• Verifying that our teams within the Cosmos service are each aware of what the other is working on, which reinforces common voice and project direction in documentation.

We believe that it is difficult for an individual team member to find all errors and updates themselves, and that it takes different thought processes, skill sets, and experiences to create and maintain documentation that effectively supports the team. While the above suggestions may not be a perfect fit for your organization, investing time into quality documents does pay its dividends. A recent GitHub Octoverse report found that “in both open-source projects and enterprises, developers see about 50% productivity boost.”

TL;DR - You Need to be Good at Documentation

Cybersecurity teams are trusted advisors to their clients and frequently receive accelerated access to an organization’s most sensitive data. Therefore, properly documenting every step of the process is of the utmost importance for a security team to operate safely in a methodical manner and preserve the safety of the client organization. Being entrusted with an organization’s digital livelihood requires logical, detailed documentation to rely on during each phase of any security engagement whether it be a pen test, product security review, red team exercise, or supporting continuous offensive security solutions.

Plus, being good at creating documentation is a skill that you can take with you across different teams, security disciplines, and even companies. With the impacts of the Great Resignation movement upon us, security teams may be more depleted of resources than ever, so any extra skills you can offer may be warmly welcomed. There will always be a need for somebody on the team that knows how to track the details. And creating documentation can be a great way to connect with different people that you may not otherwise work with closely, as you define their roles or responsibilities within the writing process.