Skip to main content

Write and organize pages

Once the source material is clear, the next job is placing the content in the right part of docs_ui.

Use the hosted IA on purpose​

Curated product docs live under docs/<project>/.... Match the folder structure to how people actually browse:

  • start-here: overview, quickstart, and first concepts
  • build: how to integrate or extend the repo
  • observe: operational behavior, troubleshooting, or runtime visibility
  • reference: API and protocol material
  • examples: concrete walkthroughs and case studies

Do not create folders just because the source repo has them. Create folders that help the hosted docs read well.

Decide what to author and what to import​

Author pages directly in docs_ui when the page:

  • synthesizes multiple source repos
  • explains the product story for newcomers
  • needs custom diagrams or cross-links
  • should stay stable even if a source repo reorganizes itself

Import a page through scripts/doc-metadata.mjs when the source repo already owns the reference material and the hosted docs should track it closely.

Update navigation with the content, not after it​

When you add or move pages, update the nav in the same change:

  • sidebars.ts for the main product docs
  • src/data/projects.ts for project entry points and Bitbucket links
  • _category_.json files when folder labels or generated indexes need adjustment

That keeps the docs readable while they are being built, not only after a later cleanup.

For diagrams, prefer Mermaid fences directly in the page when the diagram is simple enough to live with the docs:

```mermaid
flowchart TD
  Source --> Runtime
  Runtime --> Outputs
```

For source control links, point people to the project-level Bitbucket link in `src/data/projects.ts` or add in-page links only when a specific file or folder matters to the explanation.

## Good page-writing habits

- open with the shortest useful explanation of why the page exists
- keep commands copy-paste ready
- link to the actual repo doc or example instead of paraphrasing it twice
- prefer one strong page over three thin pages that repeat each other

## Next steps

- Continue to [Sync and verify](/integrations/manual/sync-and-verify)
- If you need to refresh an existing project instead of adding content from scratch, continue to [Update an existing repo](/integrations/manual/update-an-existing-repo)