Skip to main content
This knowledge base improves every time someone documents a problem they solved, a workaround they discovered, or a procedure that has changed since an article was last updated. Submitting a guide suggestion does not require writing experience or special tooling — it requires clear thinking about the problem you solved and a willingness to write it down in a way the next person can follow. This page explains what makes a guide worth publishing, how to structure your submission, and how to get it reviewed and published.

​
What Makes a Good Troubleshooting Guide

Not every solved ticket needs its own article, but some genuinely do. A guide is worth writing when:
  • The issue recurs regularly — you have seen it more than once, or you expect others will encounter it.
  • The fix is non-obvious — it took meaningful investigation to resolve and is not covered by the vendor’s own documentation.
  • The steps are repeatable — another engineer following the same steps on a similar system should reach the same outcome.
  • The scope is specific — the guide addresses one clearly defined problem, not a broad topic area.
Short guides are usually better guides. If your article exceeds around 1,500 words, consider whether it is covering more than one distinct problem. If so, split it into separate, linked articles.
A high-quality guide has four essential qualities:
A reader should be able to confirm within the first thirty seconds that they are in the right place. List the exact error messages, log entries, or observable behaviours that indicate this specific problem — not generic descriptions that could apply to dozens of issues. Include the affected operating system versions, application versions, or hardware models where relevant.
Each step should contain exactly one action, written as an imperative sentence (“Open the Services console” rather than “The Services console should be opened”). Include the command or UI path, the expected output or result, and what to do if the result is unexpected. Never write a step that says “fix the issue” — break every action down to its smallest meaningful unit.
After every fix attempt, tell the reader what success looks like and what failure looks like. “The service will show a status of Running” is useful. “The problem should be resolved” is not. Explicit expected outcomes allow readers to self-triage without re-reading the whole article.
Every guide must end with a clear escalation instruction. Specify which team or individual to contact (for example, the network engineering team, the vendor support portal, or the security operations centre), what information to include in the handover, and what ticket priority to assign. An article without an escalation path leaves readers stranded when the documented fixes do not work.

​
Style Conventions

Consistent style makes the knowledge base easier to read and faster to scan. Apply these conventions in every guide you write.
  • Active voice, second person. Write “Run the following command” not “The following command should be run.” Address the reader as “you” throughout.
  • Present tense. “Click Save” not “Click Save and the settings will have been applied.”
  • Exact UI labels in bold. When referring to a button, menu item, or field name, bold it to match what the reader sees on screen: Settings, Apply, Advanced Options.
  • Commands in code blocks. Every command, file path, registry key, and exact output string must appear in a fenced code block. Never embed commands inline in prose where they can be misread.
  • Screenshots for complex UI flows. Include annotated screenshots when a UI path is difficult to describe in words alone. Annotate with numbered callouts rather than arrows, and caption every image with a brief description of what it shows.
  • Version specificity. If a procedure applies only to specific versions of an operating system or application, state this at the top of the article and in each step where the UI or behaviour differs.
  • No jargon without definition. Spell out every acronym on first use. If a concept requires background knowledge, link to an existing guide or a reputable external reference rather than embedding a lengthy explanation.
Run your draft through a grammar checker before submitting. Most writing issues that slow down review — passive voice, unclear antecedents, missing articles — are caught automatically by tools like Grammarly or the Hemingway Editor.

​
Guide Template

Use the following Markdown template as the starting point for every new guide. Copy it, fill in each section, and remove any placeholder text before submitting.

​
Submission Process

1

Draft your guide using the template

Copy the template above into your preferred text editor. Fill in every section — do not leave placeholder text in the submitted draft. Pay particular attention to the frontmatter fields: the title must be 50–60 characters, and the description must be a single sentence of 130–155 characters that clearly states the problem and the resolution approach.
2

Self-review against the quality checklist

Before submitting, verify the following: symptoms are specific and list exact error messages; every fix step is numbered and contains one action; each fix section ends with an expected outcome statement; the escalation section names a real team or queue and lists the information to include in the handover; all commands are in fenced code blocks; active voice and second person are used throughout.
3

Submit your draft for review

Use the feedback link at the bottom of any knowledge base page — or email the address shown on the contact page — to submit your draft. Include a one-line summary of the problem the guide addresses and the affected platform or product. A reviewer will acknowledge your submission and let you know if any clarifications are needed before publication.
4

Address review feedback

Reviewers may request clarifications, additional steps, version specificity, or style corrections. Address each comment in turn — most guides clear review within two business days of the feedback being addressed.
5

Confirm publication

Once your guide is approved, you will receive a confirmation with the live URL. Share the link in the original ticket or incident record so the connection between the real-world event and the documented solution is preserved for others who encounter the same issue.

​
Updating an Existing Article

If you find that a guide is out of date, incomplete, or contains an error, you do not need to write a new article — submit an amendment.
Do not silently edit a published guide if the change affects the recommended fix for a step that users may currently be mid-way through. Flag the change when submitting so that a version note can be added and affected readers are made aware of the update.
For minor corrections (typos, broken links, outdated version numbers), use the feedback link on the article page and include the current text alongside the corrected text. For substantive changes — new fix steps, revised diagnostics, updated escalation paths — follow the same submission process as a new guide, starting from step 2 of the process above.
The best time to write or update a guide is immediately after resolving an incident, while the steps are fresh in your memory and the diagnostic outputs are still open in your terminal. A guide written an hour after resolution is ten times more accurate than one written a week later from memory.