Treat documentation as part of the change
When behavior changes, the most reliable time to update documentation is in the same pull request. Reviewers can compare implementation and explanation together, and version tags keep the docs aligned with the released code.
- Keep a focused README near the component it explains.
- Require docs updates when public behavior, configuration, or operational steps change.
- Use link and style checks in continuous integration.
- Assign clear ownership for high-risk runbooks and reference pages.
Choose the document type before writing
A tutorial teaches through a sequence. A how-to guide solves a task. Reference material describes exact behavior. An explanation provides context and tradeoffs. Mixing all four into one long README makes each harder to use.
Architecture decision records are another useful pattern: record the context, decision, alternatives, and consequences while the reasoning is still fresh. Markdown keeps the record close to the code without requiring a separate publishing workflow.
Make code examples testable and honest
Readers copy examples. Include required imports, realistic names, expected output, and the relevant error path. If the snippet is intentionally incomplete, say so. A small tested example is more valuable than a large block that merely looks plausible.
```bash # Validate docs before opening a pull request npm run lint npm run typecheck ``` Expected result: both commands exit with status 0.
Optimize for reviewable diffs
Use one sentence per line only if the repository adopts that convention consistently; otherwise wrap naturally and let tooling handle presentation. Avoid reformatting an entire file during a factual edit. Stable headings and reference-style links can make large documents easier to change without noisy diffs.
- Give headings specific names that remain useful in generated anchors.
- Keep tables narrow and avoid prose-heavy cells.
- Use relative links for files that move with the repository.
- Do not paste secrets, private logs, or unredacted production data into examples.
Use conversion as a migration starting point
A Word file, spreadsheet, PDF, or slide deck can contain valuable knowledge that does not yet fit a docs-as-code workflow. Converting it to Markdown removes much of the presentation layer, but a developer still needs to normalize headings, repair links, choose file boundaries, and confirm technical accuracy.
Keep the source document until the converted version has been reviewed. For calculated data or signed records, the original may remain the source of truth even after a readable Markdown snapshot is added to the repository.