Short and findable

Write short sections that people and agents find by search.

Keep each read short

Readers open one section at a time, so give each section one idea and keep it to about 30 lines. npx astryx doctor warns on any read over 32 KB.

  • When a section needs a second idea, split it into two sections.
  • Keep a topic to a few sections. When it grows past five, split it into more guides in your docs section.
  • A topic with more than one section reads as its section list. Readers open one section by its key, or the whole topic with --full.
bash
# The section list
npx astryx docs acme/deploying
# One section
npx astryx docs acme/deploying check-before-you-ship
# Everything
npx astryx docs acme/deploying --full

Lead with the summary

A section's first prose block, or its first list item, is its summary in section lists and search results. Make it answer the section's question in one or two sentences.

  • The summary is cut at about 240 characters.
  • A code block first does not count: the summary comes from the next prose block.
  • Open with the answer, not with background.
text
build-before-you-ship  Build before you ship - Build the app, then upload the `dist` folder to your host.

Make docs findable

Search ranks a query that matches a whole title, or an identifier in backticks, above words in body text. Title each section with the task a reader searches for.

  • Name the task in the words a reader types, such as "Deploy to production". Avoid titles such as "Overview" or "Details".
  • Write field names, file names, and error codes in backticks, such as deployTarget: search treats each one as a keyword.
  • Other words in the summary and body match too, but rank below titles and identifiers. The summary shows under each hit, so make it answer the query.

Test a doc the way a new reader finds it: search for the question, and check that the first hit answers it. Quote a query of more than one word.

bash
npx astryx search "place a doc" --type doc