Knowledge Base Article Formats for Cybersecurity Tech Platforms (Diataxis Documentation Framework)

Knowledge base article formats can help your users get quick answers to their questions – meaning fewer support tickets.

In the final quarter of 2024, we conducted a wide-ranging review of some of the top cybersecurity companies’ knowledge bases. Layouts, outlines, and structures vary wildly. Consistency is rare. Content ranges from scant to unwieldy and therefore overwhelming. Navigation is sometimes patchy. Consequently, users will sometimes find that it takes more time than necessary to find an answer to their question.

The software vendors who do it best value consistency over everything else. Having a set structure and template for knowledge base article formats enables consistency to happen.

So, let’s look at the best knowledge base article formats for cybersecurity tech platforms with reference to the Diataxis documentation framework that addresses content, architecture, and form for technical documentation.

Most screenshots are taken from Invicit.com to help illustrate the points. Sensei helped Invicti (formerly Netsparker) to develop the initial content for their knowledge base.

Why You Need to Devise Knowledge Base Article Formats

Growing enterprise software development companies will usually have at least one technical writer providing technical writing services. But, they will typically have many others contributing to the documentation. There’s an old saying that “Too many cooks spoil the broth”, thought to be inspired by 16th century English historian, John Hooker, who wrote in The Life and Times of Sir Peter Carew:

There is the proverb, the more cooks the worse potage.”

But, consistency is possible by deploying a few key documents:

• Client brief – to establish the purpose and goals for the documentation
• Buyer personas template – to ensure writers knows who they’re writing for
• Writing style guide – to help align everyone on matters of style
• Tone of voice guide – to ensure the documentation feels like the company’s usual voice
• Naming conventions – to ensure consistency with names for the company, its products, individual product features, and screen elements (not as common as you’d expect)
• Templates – to set out the layout, structure, format, and typical types of content for knowledge base articles
• Guidelines for documentation reviews – to help editorial and technical reviewers know what to look for in order to get articles ready for publication

Types of Knowledge Base Article Formats (or Templates) as Outlined by the Diataxis Documentation Framework

Here are a few different types of articles you’d expect to see in any body of software documentation, listed according to the Diataxis (δῐᾰ́τᾰξῐς) documentation framework:

• Explanation (what we call ‘Capability Overviews’ and ‘Topic Overviews’) – when readers need to understand something
• How-to Guides (what we call ‘Topic How-tos’) – when readers have a goal and need a quick answer so they can get on with a task
• Reference (what we call ‘Reference Documentation’) – when readers need a single piece of information
• Tutorials (what we call ‘Demos’) – when readers need to watch and listen in order to learn how something works

These four types are further placed into a quadrant according to whether they are for: Action, Application, Cognition, or Acquisition. Each type straddles two quadrants.

It’s essential to create templates for each type to help speed up the creation and update of support documentation topics for your knowledge base.

In each heading below, the headings are as follows:

• Sensei’s template types first (e.g. Capability Overview)
• Diataxis documentation framework types in brackets (e.g. Explanation – Understanding)

Capability Overview (or ‘Explanation – Understanding’ in Diataxis)

We refer to these as Capability Overviews (but they fit into the Explanation type in the Diataxis documentation framework). Every knowledge base should contain a series of topics that provide a broad overview of the big categories into which smaller topics (Topic Overviews) will fit.

For example, in the case of an API, application, or network vulnerability scanner, Capability Overviews would typically include: Getting Started, Account, Discovery, Targets, Scans, Reporting, Issues, Technologies, Integrations, or Remediation. Users should be able to see at a glance what the software platform or product enables users to do.

This is how we organise the content in a Capability Overview article:

• Title (e.g. Overview of Reports, Introduction to Reports)
• Introduction to the product’s capability explaining what the big capability of the product is, what it enables users to do, and what outcomes users can expect
• Links to a few closely related Capability Overviews and Topic Overviews
• Information and Warning boxes to highlight key aspects of the topic
• Further sub-headings under which we explain key concepts or aspects of that topic, sometimes arranged in tables depending on various factors
• Information on which articles to read next, including links to How-to Topics

Topic Overview (or ‘Explanation – Understanding’ in Diataxis)

We refer to these as Topic Overviews (but they fit into the Explanation type in the Diataxis documentation framework). Every knowledge base’s Capability Overviews (categories) should contain a series of Topic Overviews that focus on a key feature (of one of the main Capability Overviews) of the product.

Each Topic Overview should be grouped around a Capability Overview.

For example, in the case of an API, application, or network vulnerability scanners, the setup would look something like this:

• The Capability Overview – ‘Overview of Reports’ (one of the main capabilities of the platform)
• Topic Overview – ‘Built-In Reports’ (one of the main features of the Reports capability)

This is how we organise the content in a Topic Overview article:

• Title (e.g. Built-in Reports or Working With Built-in Reports)
• Introduction to the topic explaining what the feature enables users to do
• Links to a few closely related Topic Overviews and Topic How-tos
• Information and Warning boxes to state who has access to the feature and anything users should know before they proceed
• Further sub-headings under which we explain key concepts or aspects of that feature, sometimes arranged in tables depending on various factors
• Information on which articles to read next, including links to How-to Topics

Topic How-to (‘How-to Guides – Goals’ in Diataxis)

We refer to these are How-to Topics (but they fit into the How-to Guides type in the Diataxis documentation framework).

How-to topics should contain a series of numbered procedures that explain how to view, create, amend, share, or otherwise use the various features of the platform.

Each Topic How-to should be grouped around a Topic Overview.

For example, Topic How-tos within a Scans topic might include ‘How to View the Scan Report’ or ‘How to Scan Applications in an IP Range’.

This is how we organise the content in a Topic How-to article:

• Title (e.g. How to View the Scan Report in Invicti Enterprise)
• Information and Warning boxes to state who has access to the feature and anything users should know before they proceed
• Further sub-headings under which we explain key concepts or aspects of that feature, sometimes arranged in tables depending on various factors
• Information on which articles to read next, including links to How-to Topics

Reference Documentation (or ‘Reference – Information’ in Diataxis)

We refer to these as Reference (but they fit into the Reference type in the Diataxis documentation framework).

Some topics are merely for reference. Reference documentation tends to be positioned toward the end of a knowledge base.

Examples include:

• API documentation, where tables of X are listed and explained, usually accompanied with code samples
• Tables of error codes, explanations, and a link to the topic on how resolve them

This is how we organise the content in Reference Documentation:

• Title (e.g. API Guide, Error Codes)
• Introduction to the reference, explaining briefly how it might be deployed by developers with links to the Topic Overview or Topic How-to
• Tables listing the code parameters, options, and code samples
• Links to a few closely related other parts of the Reference

Demos (‘Tutorials – Learning’ in Diataxis )

We refer to these as Demos (but they fit into the Tutorials type in the Diataxis documentation framework).

Every knowledge base should contain the following demos:

• A few videos on key concepts, and essentially what the product enables users to achieve – with some subtle marketing positioning and messaging
• At least one video demo explaining key capabilities for the product (things that get their own Capability Overview)
• At least one video demo showing how each the most important features work (things that get their own Topic Overview) – or, if this is initially too much to tack, at least a list of priorities
• Anything that can be difficult to grasp, such as pre-requisites, licensing, Installation or Integrations

Each demo should be accessible from a Resources page and embedded in the relevant part of the knowledge base.

For example, in the case of an API, application, or network vulnerability scanner, demos might include:

• Web application vulnerabilities and the potential hacks and consequent data breaches that can occur
• How Scan Policies help app developers save time
• How to Configure URL Rewrite Rules
• How to Integrate with JIRA

Knowledge Base Article Formats Decrease Writing and Updating Time and Increase Consistency

If your platform’s knowledge base is chaotic and disorganised and it takes a long time to update your documentation, or if you need expert information architecture and help with knowledge base article formats, contact Sensei today.