Knowledge Base & Internal Documentation Writing Exercises

The standard structure is: title (action-oriented, e.g., "How to reset your API key"), a one-sentence overview of what the article covers and who it is for, a prerequisites section listing what the reader needs before starting, numbered steps (one action per step), expected results after each significant step, a troubleshooting section for common errors, and a "related articles" footer. Each step should begin with a verb in the imperative mood: "Click", "Navigate to", "Enter", "Select". Avoid passive voice in procedural instructions — "the button should be clicked" is harder to follow than "click the button."

Runbooks use imperative, unambiguous language throughout. Steps are numbered, not bulleted, because order matters. Each step includes: the action to take, the command to run (in a code block), the expected output, and what to do if the output is unexpected. Recommended phrasing: "Run the following command:", "You should see output similar to:", "If the service fails to start, check [log location] for the error code and proceed to step 8." Runbooks should be written so that someone unfamiliar with the system can follow them under pressure at 3 AM.

Organise by symptom, not cause. Readers arrive with a symptom — "the import button is greyed out" — not a root cause. Structure each entry as: symptom (in the user's language), possible causes (brief), diagnostic steps (numbered), and resolution. Use headings that mirror how a user would describe the problem. Useful phrases: "If you see this error message...", "This typically occurs when...", "To confirm this is the cause, check...", "To resolve this issue, follow these steps." Test every troubleshooting path yourself before publishing.

Common structural terms: title, subtitle, abstract or summary (a 1–2 sentence overview), body, callout or note (a highlighted block for warnings or tips), code block (formatted text for commands or code), screenshot or annotated image, prerequisite, procedure (a set of numbered steps), expected result, and related articles. Editorial metadata terms: author, reviewer, last reviewed date, article ID, category, and tags. In wiki culture you will also see terms like stub (an article that exists but needs expansion) and deprecated (content that is no longer current but retained for reference).

Use a consistent callout hierarchy: NOTE for supplementary information that helps but is not critical; TIP for optional best practices; IMPORTANT for information the reader must not miss; WARNING for actions that could cause data loss, service disruption, or security issues; CAUTION (less common) for reversible risks. Standard phrasing: "WARNING: Running this command will permanently delete all records in the table. Ensure you have a verified backup before proceeding." Always place warnings before the step they relate to — never after.

Single-sourcing means writing content once and reusing it across multiple documents or contexts rather than copying and maintaining it in multiple places. In practice, this is implemented through content reuse patterns like transclusion (embedding one article's content into another), shared snippets or partials, and structured content systems. The business value: when a procedure changes, you update it in one place and the change propagates everywhere. In conversation: "The installation prerequisites are single-sourced — they appear in the quickstart guide, the admin manual, and the upgrade guide, all pulling from the same source snippet."

Internal search optimisation focuses on matching the vocabulary users actually type when searching — which is usually problem-oriented and informal. Best practices: include the exact error message text in the article body or title so users who search by error code find it; use synonyms for common terms (e.g., "two-factor authentication / 2FA / two-step verification"); write the title in the form of a question if the article answers a specific question; and tag articles with product area, user role, and feature name. Review search analytics to identify queries with no results and create articles to fill those gaps.

Internal wikis favour concise, direct, plain English. Use second person ("you") rather than "the user" or "one should." Write in the active voice. Avoid marketing language — wikis are not promotional. Use short sentences and short paragraphs. Numbered lists for sequential procedures, bulleted lists for non-sequential information. Avoid jargon without explanation. Date all pages with a "last reviewed" date and assign an owner. Common conventions: bold for UI elements ("click Save"), monospace for commands and file paths, italics sparingly for emphasis or introducing a new term.

The title should answer the question "what is this article about?" unambiguously. Best practices: use action-oriented titles for procedures ("How to configure SSO", "How to add a team member"), use noun-phrase titles for reference articles ("API rate limits", "Supported file formats"), and include the product name if the knowledge base covers multiple products. Avoid vague titles like "Settings" or "Configuration" — they tell the reader nothing about which setting or configuration. A/B test titles by reviewing which search queries land on the article and whether users bounce back to search.

A knowledge base article is written for end users or customers — it explains how to use a product, troubleshoot an issue, or understand a concept, using accessible language. A runbook is written for operations or engineering teams — it documents the exact steps to perform a specific operational procedure, often under time pressure, and assumes significant technical knowledge. Runbooks include command-line instructions, expected outputs, rollback steps, and escalation paths. KB articles are reader-facing; runbooks are operator-facing. In many organisations, runbooks live in an internal wiki separate from the customer-facing knowledge base.