uplift.page
← library
prompt📝 Docs & writingv2 · updated 2026-06-12

Documentation that gets read

Docs site with quick starts, task guides, and generated reference.

Run it as a prompt

Paste this into any AI agent, or fetch it: curl -s https://uplift.page/api/v1/prompts/api-docs-site/raw

prompt.md
# Documentation that gets read

Documentation where a new user succeeds in five minutes and a returning user finds the exact parameter in ten seconds.

## Recommended stack

- **Starlight (Astro) or Nextra** - site. Markdown-first docs with search, sidebar, and dark mode solved.
- **Generated API reference (OpenAPI/TypeDoc)** - reference. Reference that compiles from source can't lie.
- **Copy-pasteable examples (tested in CI)** - trust. Examples that run are the difference between docs and fiction.

## Build steps

1. Structure by reader intent: Quick start → Guides (tasks) → Reference (lookup) → Concepts (why).
2. Quick start: working result in ≤ 5 copy-pasteable steps with expected output shown.
3. Write guides as verbs ('Send your first event'), one task each, no forks of 'if you want X'.
4. Generate reference from code annotations; lint CI fails on undocumented public surface.
5. Test doc snippets in CI (extract + run) so examples can't rot.

## Watch out for

- Wall-of-prose concepts before the reader has seen it work.
- Screenshots of code instead of text (unsearchable, uncopyable).
- 'Simply' and 'just' hiding three missing steps.

## Definition of done

- A stranger reaches 'it works' in 5 minutes unassisted
- Search answers the top 10 support questions
- Docs build fails when public API loses its docstring

The full prompt

Documentation where a new user succeeds in five minutes and a returning user finds the exact parameter in ten seconds.

Recommended stack

  • Starlight (Astro) or Nextra - site. Markdown-first docs with search, sidebar, and dark mode solved.
  • Generated API reference (OpenAPI/TypeDoc) - reference. Reference that compiles from source can't lie.
  • Copy-pasteable examples (tested in CI) - trust. Examples that run are the difference between docs and fiction.

Build steps

  1. Structure by reader intent: Quick start → Guides (tasks) → Reference (lookup) → Concepts (why).
  2. Quick start: working result in ≤ 5 copy-pasteable steps with expected output shown.
  3. Write guides as verbs ('Send your first event'), one task each, no forks of 'if you want X'.
  4. Generate reference from code annotations; lint CI fails on undocumented public surface.
  5. Test doc snippets in CI (extract + run) so examples can't rot.

Watch out for

  • Wall-of-prose concepts before the reader has seen it work.
  • Screenshots of code instead of text (unsearchable, uncopyable).
  • 'Simply' and 'just' hiding three missing steps.

Definition of done

  • A stranger reaches 'it works' in 5 minutes unassisted
  • Search answers the top 10 support questions
  • Docs build fails when public API loses its docstring

Served from the uplift.page library and refreshed within 5 minutes of every update.