mrpunyapal/docsmith/docs-writing

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

Every page accepts these keys:

Always write title and description. Descriptions do real work: they appear in search results and LLM exports.

Linking between pages

Write links the GitHub way, pointing at the .md file:

See [Versioned Docs](versioned-docs.md) for details.

Docsmith rewrites these to the built page URLs at build time, including relative paths (../installation.md) and fragments (configuration.md#options). A link to a .md file that is not part of the build is left untouched, so double-check those during review.

Media files

Keep images, videos, and PDFs next to the Markdown that references them. Docsmith copies them into the build and rewrites relative references so they resolve from the built URL:

![Diagram](images/diagram.png)
 
<video controls src="media/demo.mp4"></video>
 
[Download the spec](files/spec.pdf)

Remote URLs and root-relative paths are not rewritten. Reference only files that exist in the source tree; a missing file stays broken in the output.

Structure that holds up

• Put runnable code before prose explanations. Show, then explain.
• Use fenced code blocks with a language tag so highlighting works.
• Document options in tables: name, what it does, default.
• Use numbered steps only for sequences, bullets otherwise.
• Write in second person ("run", "you get"), active voice, present tense.
• One idea per sentence. Cut every word that does not change meaning.
• No marketing adjectives in reference pages. Save opinions for guides.

Naming

• File names become URLs: lowercase, hyphenated, stable. Renaming a file breaks every inbound link.
• Name pages after the task or concept ("Remote Sources"), not the tool section ("Feature X").
• Keep sibling pages parallel: if one starts with "Install", siblings should not start with "How to".

Multi-version and hub builds

• Keep the same file names across versions so pill buttons can jump between versions on the same page.
• Pages that exist in only one version fall back to linking at that version's home; prefer closing such gaps.
• In hubs, each set is independent: duplicate shared content rather than cross-linking between sets.

Review checklist

1. Does every page have title, description, and one H1?
2. Do all internal links point at .md files that exist in the build?
3. Do image, video, and download paths point at media files that exist in the source tree?
4. Is the sidebar order deliberate (order: or navigationOrder()), not accidental?
5. Would a newcomer understand the first screen without reading another page?
6. Are code blocks copy-pasteable with no hidden context?
7. Does the landing page have a quick start and the main use case, not a catalog?