Writing & Linking Docs in the Troubleshooting KB

This is the working guide for anyone adding an issue to the KB — written for a junior dev who needs to go from “something’s broken” to “here’s exactly what to check” as fast as possible.

1. Where things live

wp-admin → WDM Docs → Add New Issue creates one entry.
Each entry is one specific, reproducible problem — not a whole module. “Billing expiry date doesn’t update after payment” is a good issue. “Billing is broken” is not — split it up.

2. Fields, in the order you’ll fill them

Field	Where	What goes in it
Title	Main title field	The symptom as someone would search for it: “Team/mine toggle doesn’t reload sites”, not “Bug #412”.
Module	Sidebar, right column	Pick the module this lives in. Use the exact same module names as the Maintenance Dashboard codebase (Billing, Reliability, Basecamp, Reports, Time Log, Site Dashboard, Integrations, Sites/Archived) — this is what drives the archive grouping and sidebar nav, so an invented module name creates an orphan section nobody finds.
Severity	Sidebar, right column	`Blocks All Users`, `Single Site`, or `Cosmetic`. If you’re unsure, pick the more severe one — it’s easier to downgrade later than to have someone miss a real blocker.
Overview (main editor)	Main content area	Optional. Use only if the issue needs a sentence or two of context before the Symptom box (e.g. “this only shows up after the 1.8.1 Billing release”). Most issues can skip this.
Symptom	Meta box	What’s observed — the exact error text, what the user reported, what the screen shows. Not your theory about the cause.
Where to Look	Meta box	One file/class/method reference per line, e.g. `includes/modules/class-billing.php :: add_period()`. This renders as a code-styled reference box so a junior dev can jump straight into the codebase.
Investigate	Meta box	One check per line, in the order you’d actually run them — first thing to check first. This becomes the numbered “Investigate” stage.
Resolve	Meta box	One fix step per line, assuming the cause from Investigate is confirmed.
Prevent	Meta box	Optional, but write it when you can — a regression test to add, a guard clause, a habit to build. Skipping this is fine for a one-off cosmetic issue; don’t skip it for anything that blocked a client.
Related Issues	Meta box, sidebar	Check any other KB entries that share a root cause, a file, or tend to get confused with this one.

3. Writing style — keep it scannable

One idea per line in Investigate/Resolve/Prevent — the layout depends on it (each line becomes its own numbered/bulleted item).
Write imperative, concrete steps: “Check md_billing_status meta for the site post”, not “Look into the billing status logic.”
Symptom is what you’d paste into a support reply. Investigate/Resolve is what you’d say to a teammate over a shoulder-tap.
If a step depends on DevTools (per the main plugin’s own verification routine — Network tab filtered to admin-ajax.php, or the mdAjax() console errors), say so explicitly; don’t assume it’s obvious.

4. Linking issues together

There are two ways to link entries — use both when it’s relevant:

Related Issues meta box (structured). This is what powers the “Related Issues” card grid at the bottom of the single page, and it’s a two-way relationship in spirit — if issue A lists B as related, go add A to B’s Related Issues too, so a reader arriving at either one finds the other.
Inline links in the Overview/content editor (contextual). If a step in your Investigate list is “this is actually the same root cause as the Reliability sync issue,” link the phrase directly to that entry’s permalink using the normal block editor link tool. Use this when the connection needs explaining, not just listing.

Do not paste raw URLs — always use the actual post title as the link text, and pull the permalink from the entry itself (open it, copy the URL bar) so it survives if permalinks structure ever changes.

5. How navigation works (so you know what you’re feeding)

Archive page (/wdm-docs/) groups every published issue by its Module term, in collapsible sections. The section id is #module-{module-slug}, which is exactly what the sidebar’s “Jump to Module” links point at — so a correct Module term is also what makes deep-linking work.
Severity pills at the top of the archive filter by ?severity=slug — this reads your Severity term directly, no separate config.
Search (?s=...&post_type=wdm_doc_template) is native WordPress search scoped to this CPT — it searches Title and the main content editor. It does not currently search inside the Symptom/Investigate/Resolve meta boxes. If an issue is hard to find by title, add the key error text to the Overview editor as a sentence, even a redundant one — that’s what makes it searchable.
Single page always shows: breadcrumb → title + Module/Severity badges → Overview (if any) → Symptom → Where to Look → the numbered Investigate/Resolve/Prevent rail → Related Issues → an “At a Glance” side panel with Module, Severity, and last-updated date.

6. Quick checklist before you hit Publish

Title reads like something you’d search for
Module matches an actual Maintenance Dashboard module name
Severity set
Symptom describes what’s observed, not the cause
Where to Look has at least one real file/class reference
Investigate steps are in the order you’d actually run them
Resolve steps assume the cause is confirmed
Related Issues checked both directions, if applicable

7. One-time setup notes (for whoever installs this)

After activating the plugin, visit Settings → Permalinks and click Save once — this flushes rewrite rules so /wdm-docs/ resolves immediately. (The plugin also does this automatically on activation, but a manual save is the fallback if /wdm-docs/ 404s.)
If you ever edit assets/css/wdm-doc.css or assets/js/wdm-doc.js, bump WDM_DOC_VERSION in wdm-documentation.php so browsers don’t serve a stale cached copy — same convention the main dashboard plugin uses for MAINTENANCE_DASHBOARD_VERSION.
The templates render inside Astra’s normal header/footer (via template_include), so global theme settings (Customizer typography, container width, breadcrumb toggle) still apply on top of this design.