> ## Documentation Index
> Fetch the complete documentation index at: https://docs.derekdinh.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Contributing Troubleshooting Guides to the Knowledge Base
> Submit new guides or improvements using the standard template, style conventions, and review process to keep the knowledge base consistent and actionable.
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.
```markdown theme={null}
---
title: "[Concise description of the problem being solved — 50–60 characters]"
sidebarTitle: "[2–3 word title]"
description: "[One sentence summarising the problem and fix — 130–155 characters]"
---
[Opening paragraph: one to three sentences explaining what this guide covers,
which systems or versions it applies to, and the typical context in which the
problem occurs. Do not start with a heading.]
## Symptoms
You are likely affected by this issue if you observe one or more of the following:
- [Exact error message or observable behaviour #1]
- [Exact error message or observable behaviour #2]
- [Affected versions, OS, or hardware if applicable]
## Prerequisites
Before starting, ensure you have:
- [Required access level, e.g. local administrator rights]
- [Any tool or file that must be present before you begin]
- [A current backup if the fix modifies system files or settings]
## Diagnostics
Complete these steps before attempting any fix. Record the outputs — you will
need them if the issue requires escalation.
1. [Diagnostic step 1 — what to run or check, and what the output tells you]
2. [Diagnostic step 2]
3. [Diagnostic step 3]
## Fixes
Work through these fixes in order. Test after each one before proceeding to the next.
### Fix 1: [Short descriptive title]
[One sentence explaining what this fix does and why it may resolve the issue.]
1. [Step 1]
2. [Step 2]
3. [Step 3]
**Expected outcome:** [Describe exactly what success looks like after this fix.]
### Fix 2: [Short descriptive title]
[Explanation.]
1. [Step 1]
2. [Step 2]
**Expected outcome:** [Describe exactly what success looks like after this fix.]
## Escalation
If none of the above fixes resolve the issue:
- **Contact:** [Team name, queue name, or vendor support portal]
- **Priority:** [P1 / P2 / P3 — and the criteria that determine which applies]
- **Include in your handover:**
- Output from the Diagnostics section
- List of fixes attempted and the result of each
- Timestamp of when the issue first occurred
- Affected user count and business impact
## Related Articles
- [Link to a related guide]
- [Link to a related guide]
```
## Submission Process
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.
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.
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.
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.
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.