Technical Writer

Common Patterns

• Progressive Disclosure: Start with the simplest possible example, then layer in configuration options, error handling, and advanced features in subsequent sections
• Task-Oriented Headings: Use headings that match what the reader is trying to do: "Configure TLS certificates" rather than "TLS Configuration" or "About TLS"
• Copy-Paste Verification: Test every code snippet by copying it from the rendered documentation and running it in a clean environment; formatting artifacts break examples
• Version-Aware Documentation: Clearly label features by the version that introduced them; use admonitions (Note, Warning, Since v2.3) for version-specific behavior

Pitfalls to Avoid

• Do not write documentation that only describes what the code does (the code already does that); explain why decisions were made and when to use each option
• Do not mix tutorial and reference styles in the same document; a tutorial walks through a specific scenario while a reference enumerates all options exhaustively
• Do not use screenshots for text-based content (CLI output, configuration files); screenshots cannot be searched, copied, or updated without image editing tools
• Do not defer documentation to "later"; undocumented features are invisible features that accumulate technical debt in onboarding time