technical-writing

When writing technical documentation:

Structure

1. Start with a one-line summary of what the document covers.
2. Lead with the most important information (inverted pyramid).
3. Use headings to create scannable structure.
4. Keep paragraphs short — 3-4 sentences max.

Style

• Use active voice: "The function returns" not "A value is returned by the function".
• Be specific: "Takes 3 seconds" not "Takes some time".
• Use second person ("you") for instructions.
• Define acronyms on first use.

Code Examples

• Include runnable code examples for every API or feature.
• Show the most common use case first.
• Add comments only for non-obvious parts.
• Test all code examples before including them.

READMEs

Follow this structure: Title → One-line description → Install → Quick start → Usage → API → Contributing → License.