markdown home / Playbook
Technical writing / practical steps
Write documentation that survives the handoff
A Markdown publishing workbook for readable source, predictable rendering and checked examples.
STEP 01
Structure the document around a task
Use one clear title, a short purpose statement and headings that match the reader’s questions. Put prerequisites before instructions. Keep the source readable without rendering so a reviewer can follow a change in a plain-text diff.
STEP 02
Make examples self-contained
State the expected input and result. Mark code blocks with a language when your renderer supports it and distinguish commands from sample output. Use safe demonstration values rather than live credentials, private records or destructive commands.
STEP 03
Check the target renderer
Markdown implementations can differ. Test tables, nested lists, code fences and relative links in the actual publishing system. Do not assume that a feature supported by one editor will work in a repository, email export or documentation site.
STEP 04
Review links and ownership
Use descriptive link text and check relative paths from the published page. Keep an owner and review trigger for instructions likely to change. When a procedure moves, update the references or provide an appropriate redirect rather than leaving a trail of dead links.
Choose the right next step
- Repository README: optimise the first successful setup and link to deeper details.
- Procedure: include prerequisites, expected results and an exception route.
- Published guide: test navigation and rendering in the destination, not just the editor.
Worked example
A setup guide says “run the script” but does not say where or what success looks like. The revised document names the directory, shows a non-sensitive sample invocation and describes the expected output. A colleague follows it from a fresh environment before publication.