Docs Style Guide

Principles

• Be concise — no filler. Make it easy to find what you're looking for
• Task-oriented — frame around what the user is trying to do, not what the product can do
• Progressive disclosure — guide from introduction to advanced use-cases. Don't throw users into the deep end
• Real examples over abstract explanations — show, don't describe
• Code snippets must be copy-pasteable — no placeholder values that silently break, no missing imports
• Prerequisites up front — don't surprise the user halfway through
• One topic per page — if you're covering two things, split it
• Link, don't repeat — reference other docs instead of duplicating content
• Scannable headings — skimming the TOC should reveal the page structure
• Show expected output — after a step, tell the user what they should see
• Consistent terminology — pick one term for a concept, use it everywhere
• Screenshots/GIFs for key product features — use visuals when they teach faster than text
• Know which type of doc you're writing — a tutorial (learning), a how-to (completing a task), a reference (looking something up), or an explanation (understanding why). Don't mix them in one page
• Tutorials should be completable — a user following every step should end up with a working result, every time
• Reference docs should be exhaustive and consistent — cover everything, use the same structure for every entry