Building an awesome security wiki: tips and tricks for busy teams

Writing documentation is hard. However, writing awesome documentation is even harder. The challenge is that security teams need good documentation more than any other technical discipline.

The primary reason is that people come and go and it is impossible to replace knowledge without documentation. Secondly, you need to justify what you are doing to the business. When the next audit comes you need to describe what you do and prove you do it. Third, security teams are constantly firefighting and good documentation can make a great difference during incident response.

Regardless, your security team doesn’t just deserve working documentation, they deserve awesome documentation. Throughout their long working day, your colleagues will be staring at tools first and documentation second. Because of this, making documentation a pleasure to work with should be a top priority for your team.

Are you building a security wiki right now? Then get Blog on Security’s ready-made security wiki template! It’s comprehensive, easy to import, battle-tested and an absolute time-saver.

Want to build an awesome wiki? Be logical and helpful

Making a security wiki that is a pleasure to work with is easier than you think: it just needs to be logical and helpful.

Logical in this context means that the documentation should have a clear logical structure behind it. A logical structure helps the reader with understanding intuitively why a specific page exists and where it is located in the overall security wiki.

Helpful in this context means that each documentation page genuinely help readers get the information they are after. Be mindful that this is not just about including relevant content, but also displaying the content in a manner which promotes fast information retrieval and minimal cognitive load on your readers.

Logical structure

Avoid building a security wiki haphazardly and by slapping together different parts from different documentation sources. You’ll save yourself (and your readers) a lot of pain down the line. Fortunately, building a logical structure for your security wiki is not rocket science. However, it does require some thinking! After all, a security wiki is different from an Information Security Management System which has to be built by following a specific standard (ISO 27001:2022). You have more creative freedom with your security wiki.

The formula is simple: first, define the goal of your security wiki. Is it to educate the business as to what the security team does? Is it to support your team during daily security operations? Secondly, identify what minimal body of knowledge is needed to meet your goal. If your goal is to explain why the security team is and what it does, it follows that you should build content that addresses both of these aspects. Thirdly, identify the minimal set of documents needed to supplement your chosen body of knowledge.

Using this formula, an example logical structure could be as follows:

Such a formula forces you into producing a core set of documents that are mutually exclusive and collectively exhaustive. By doing so, each document in your wiki will contribute to the overall aim, it will have a precise reason for existing and will not overlap with other documents.

If your structure is sufficiently simple (as it should be) and logical your users will intuitively understand where they are in the wiki. Additionally, they’ll be able to quickly grasp where additionally needed information is located in other areas of the wiki.

Helpful content

To create helpful content, the first obvious step is to make sure that the content in your wiki is relevant to readers. However there are another two things that you should be mindful of: simplicity of language and ease of consumption.

Simple language is clear and easy to understand. It reduces the likelihood of misinterpretation or confusion, allowing readers to grasp information quickly and accurately. Moreover, simple language caters to a broader audience, including those with varying levels of expertise or language proficiency. It ensures that the documentation can be easily understood by both beginners and experienced users.

Additionally your users will be more likely to adopt and implement the information provided in documentation if it is presented in a straightforward manner. Complex language may discourage users from understanding and adopting the recommended practices or solutions. Finally, complex language can increase cognitive load, making it harder for readers to absorb and retain information. Simple language minimizes cognitive strain, allowing users to focus on understanding and applying the content.

You can also reduce cognitive load by lowering “reading burden”. One example of this is using GIFs to reduce the amount of text necessary in every page. GIFs are a powerful tool as they can provide infinitely more detail and guidance to readers while requiring a fraction of the text necessary to explain the underlying process.

Benefits of having an awesome wiki

Effective and comprehensive documentation plays a critical role in ensuring organizational resilience in the face of digital threats. In this context, well-crafted documentation serves as an enabler for lean security teams operating under pressure.

Clear and detailed documentation facilitates seamless communication within the team, ensuring that all members possess a unified understanding of protocols, procedures and technologies. It also acts as a reference point, enabling swift and accurate decision-making in the face of ongoing incidents. During an emergency, your team will know who to contact and when.

Furthermore, great documentation promotes knowledge sharing and transfer, enhancing a team’s overall resilience in safeguarding key operational information. In essence, the benefits of exceptional documentation extend beyond mere record-keeping: they are integral to the strategic effectiveness and operational cohesion of your team.

In cybersecurity, one way to ensure strategic effectiveness and operational cohesion is by ensuring that security operations are auditable, asynchronous and automated. Effective documentation is the glue tying together these three properties. Let’s look at them individually:

• Auditable: Effective documentation in cybersecurity ensures transparency and auditability, key elements for a well-functioning environment that can explain its value to the business. Transparent documentation provides clarity on security policies, procedures and technology configurations. This transparency facilitates collaboration, enabling team members to work cohesively towards common goals. Additionally, well-documented processes support audit trails, allowing for meticulous tracking of ongoing operations as well as changes over time. This auditability is essential for compliance with regulatory requirements, helping organizations demonstrate their commitment and alignment to security certifications and best practices. Moreover, transparent documentation is a key resource during internal and external audits. By ensuring accountability and instilling confidence in stakeholders, it showcases your team’s ability to effectively manage and protect sensitive information.
• Asynchronous: Effective documentation enables a cybersecurity team to operate seamlessly in an asynchronous manner. By clearly documenting processes, protocols, and guidelines, team members can access and understand crucial information independently of real-time communication. This asynchronous capability is particularly valuable when security incidents may occur at any time, and team members may be distributed across different time zones. Well-documented procedures allow for consistent and standardized responses to security events, even when team members are not actively collaborating. This asynchronous approach enhances efficiency, as team members can refer to documentation at their convenience, reducing dependency on synchronous communication. It also supports continuous learning and onboarding of new team members, ensuring that team knowledge is readily available and transferable across different time frames.
• Automated: Effective documentation accelerates the identification of automation opportunities within cybersecurity teams. By thoroughly documenting processes, workflows and repetitive tasks, teams gain a clear understanding of the routine aspects of their work. This clarity allows them to pinpoint areas where automation can be applied to streamline operations, reduce manual effort and enhance efficiency. Detailed documentation also provides insights into the dependencies and interactions between various security tools and technologies. This knowledge is invaluable in designing and implementing automated workflows that can integrate different technology components.

Practical tips to build great documentation

There are a variety of things that you can do to make your security wiki awesome. However, there are at least four that will save you significant time while increasing ease of consumption, these are 1) establishing documentation standards, 2) preferring technical diagrams and images to explanatory text, 3) using tags and search features and, 4) creating templates for everything.

Establish and use a consistent documentation standard

Establishing and consistently following documentation standards is key to enhancing documentation readability. By adhering to a standardized format your team can create documentation that is clear, concise and accessible.

The primary standard for technical documentation is IEC/IEEE 82079-1. However, this is a closed standard that requires payment to be accessed. Alternative guidance exists, with the best being Atlassian’s very own set of documentation guidelines.

Regardless, consistency in terminology and formatting ensures that team members can quickly locate information, reducing the time and effort required to interpret documentation. Clear documentation standards also contribute to a more predictable layout, encouraging rapid information retrieval.

Moreover, standardized documentation aids in the onboarding process for new team members, as they can quickly familiarise themselves with processes and technologies. This will accelerate their ability to comprehend and contribute to the collective knowledge of their new team.

Overall, adherence to documentation standards plays a key role in improving accessibility and comprehension, ultimately making your wiki more helpful for your team.

Prefer technical diagrams and images to explanatory text

Incorporating diagrams and images in technical documentation is a powerful strategy to provide readers with detailed information and guidance while minimizing the need for long explanatory text.

There are numerous commercial products online for drawing technical diagrams. Some of the most notable include Gliffy, Draw.io, Lucidcharts and Microsoft’s Visio. Most can be embedded in documentation platforms such as Atlassian Confluence. An excellent open-source alternative is excalidraw allowing you to design beautiful diagrams completely for free.

Visual elements such as diagrams, flowcharts, and images can effectively convey complex concepts, system architectures and processes at a glance. These offer a great visual representation that complements textual descriptions. This not only enhances the overall understanding of the material but also caters to different learning styles, making the documentation more accessible to a broader audience. Just take a look at the great example below from IBM’s Design Language to get a sense of how technical diagrams can pack a ton of information in an easily digestible style.

Visual aids enable readers to grasp intricate technical details quickly, reducing the cognitive load associated with dense textual information. By presenting information visually, technical documentation becomes more concise, engaging, and user-friendly, making it easier for readers to absorb and apply information.

Make aggressive use of tagging and search features

Implementing tagging and search features in your wiki will greatly enhance the reading experience by allowing users to quickly locate relevant information.

Tags enable the categorization of content based on topics, making it easy for readers to navigate and find specific details within a document. The search functionality further complements this process, enabling users to input keywords and swiftly retrieve the information they are after.

This saves time while also promoting a more efficient and focused reading experience. It ensures that users can access the information they need without having to sift through long documents. Tagging and search features contribute to an improved user experience, increasing the accessibility and usability of technical documentation.

Creating effective tags for documentation is not hard. However, it does require some level of planning. Some common strategies that you can follow include:

1. Being descriptive and specific: Tags should accurately represent the content they are associated with. Use descriptive terms that are specific to the topics covered in the document. Avoid generic tags that could apply to a wide range of content.
2. Using consistent terminology: Maintain consistency in your tagging terminology. Choose standardized terms that are widely understood within your organization or industry. Consistent tagging improves the reliability of search results.
3. Including synonyms: Anticipate the various terms users might use when searching for information. Include synonyms or alternative terms as tags to ensure that users can find relevant content even if they use different terms in their search queries.
4. Creating hierarchical tags: Create a hierarchical structure for tags, especially if your documentation covers a broad range of topics. This can help users navigate through broader categories before narrowing down to more specific subjects.
5. Prioritizing important topics: Assign tags based on the importance and relevance of the information. Ensure that critical topics or commonly searched terms are tagged appropriately to surface them more prominently in search results.
6. Reviewing and updating regularly: Periodically review and update your tagging system. As your documentation evolves, so should your tags. Remove obsolete tags, add new ones, and ensure that the tagging system aligns with the current content.

Create templates for everything

Pro tip: build your templates using a notation format that can be easily imported into other platforms. Markdown is a great choice for this! You can find many repositories (like this one) providing markdown templates that you can use for your documentation

Creating templates for technical documentation empowers technical teams to produce high-quality documentation consistently. Templates provide a structured framework that guides team members in organizing and presenting information in a standardized manner.

This consistency not only enhances the overall professionalism of the documentation but also streamlines the writing process. Templates also serve as a reminder of essential elements that need to be included, reducing the likelihood of style “drift”.

Moreover, by pre-defining the document structure and formatting, templates help team members focus more on the content itself, fostering a culture of frequent documentation without sacrificing quality.

This approach ensures that documentation remains clear, cohesive, and aligns with established best practices, ultimately contributing to the effectiveness of the technical team’s communication and knowledge-sharing efforts.

Conclusion

Following the above tips and tricks, however basic, will help your team produce an awesome security wiki that will serve them well across the years. It goes without saying that there are many more techniques that you can use to increase ease of consumption, such as:

• Structuring content logically with headings, subheadings, and bullet points
• Using a consistent and intuitive hierarchy to guide readers through the material
• Including a table of contents and an index for quick reference
• Implementing hyperlinks to facilitate easy navigation between sections
• Breaking down complex processes into manageable steps
• Sequencing and numbering steps to guide readers through procedures
• Using bold or italic text to emphasize important information
• Using color sparingly to draw attention to critical elements
• Maintaining a consistent style and formatting throughout the documentation
• Use a consistent font, font size, and color scheme for a professional and cohesive appearance

Regardless, the tips in this post are borne out of experience in the field. If applied consistently, they will be sufficient to produce a wiki that is a joy to work with. Ultimately, remember to take care of your documentation and write it with humans in mind. Building an awesome wiki will save you time and time again: your auditors will ask fewer questions, you’ll onboard colleagues faster and your team will become even more resilient in dealing with digital threats.