Technician Docs vs User Docs
The article explains how to fix the mapped-drive problem. Step four says "open the server console and restart the share service". Step six mentions the admin password's location. It was written by a technician for technicians, which was fine until someone published it to the portal. There, a user in accounts followed it faithfully as far as step three and then phoned to ask what a server console was. Meanwhile the user-facing version, written separately a year earlier, still describes a drive letter that was retired in the spring. Two documents, one procedure, neither right for anyone, and nobody responsible for keeping them in step.
This series is about keeping two documents for two readers without doubling the work. It covers two audiences and two documents, and why one text cannot serve both. It covers writing the runbook, precise and complete, for the technician at 02:00. It covers writing the user guide from the runbook rather than from scratch. Then comes keeping the pair in sync with one source of truth and a change that triggers a review of both. It covers what must never be in the user document, with a leak test before anything is published. And it covers the documentation set a small desk actually needs, which is shorter than you fear. A runbook tells a competent stranger how to fix it. A guide tells a hurried user how to avoid needing one.
Articles in This Series
- Two Audiences, Two Documents: Runbooks and User Guides
What a runbook is and what a guide is, why one document cannot serve both readers, the agents-only versus published split, and the two-audience comparison table. - Writing the Runbook: Precise, Complete, Followable at 02:00
Assumptions stated, commands and checks, expected output, rollback, when to escalate, the date it was last run, and the runbook skeleton. - Writing the User Guide From the Runbook, Not From Scratch
What to remove, what to add, the safe subset, plain words, and the derivation checklist. - Keeping the Pair in Sync: One Truth, Two Documents
One source of truth, linked pairs, the change that triggers a review of both, the review that checks both, and the sync register. - What Must Never Be in the User Document: The Leak Test
Admin paths, credentials, bypasses, internal names, the step that needs elevated rights, the leak test before publishing, and the leak checklist. - The Documentation Set a Small Desk Actually Needs
The minimum set: runbooks for the top problems, guides for the top questions, the scope page, the contact page, the outage page. Covers where each lives, who owns each, and the inventory.
Explore More Topics
This series is part of the QuerySolv helpdesk topic library. It covers the foundations, processes, communication, knowledge, tooling, metrics, classic ticket domains, people and strategy behind a support desk that works. The library pairs well with the software we build: QuerySolv. It is a self-hosted help desk that runs as one Windows service on your own network. It is licensed once per installation, not per agent per month.