Writing Documentation

How to write documentation pages that build well with Docsmith and that a new user can actually start from.

Too little docs: hard to start. Too much (every feature, every option): hard to find the main use case. Same outcome. The project does not get used.

• Quick start or TL;DR at the top of the landing page. Copy-paste, runnable.
• First paragraphs: the most common use case, not a feature list.
• Show, don't tell. If the user asked for screenshots or videos, put them next to the step they show, cropped to the thing that matters. Do not capture images or videos unless they asked.

Page rules

• One topic per page. If a page needs "and" in its title, split it.
• Exactly one H1 per page, matching the page title. Use H2/H3 for sections.
• Open with a one or two sentence summary of what the reader gets. Details after.
• Prefer pages under roughly 400 lines. Longer pages usually hide two topics.
• Second person, present tense. No marketing words, no em dashes.

Frontmatter