Skip to main content

Update an existing repo

Most docs maintenance is not about brand-new sections. It is about keeping an existing repo area current as commands, runbooks, contracts, and examples change upstream.

Start with the delta​

Before editing anything in docs_ui, identify what changed:

  • new commands or setup steps
  • moved or renamed source docs
  • updated architecture or runtime behavior
  • new example flows or deprecated ones
  • changed owners, reviewers, or Bitbucket links

Use the source repo first. Do not start from the existing docs page and guess what is stale.

Refresh imported pages before rewriting summaries​

If the page is imported through scripts/doc-metadata.mjs, update the source path there first and run:

make sync

Then open the regenerated page and decide whether any curated overview pages now need new summaries or links.

Update curated pages where people actually start​

The highest-value refreshes are usually:

  • overview and quickstart pages
  • commands shown in setup or verification steps
  • architecture summaries that hide recent behavior changes
  • example pages that no longer match the preferred path
  • repo links in src/data/projects.ts

Treat those pages as the front door. If they are stale, the rest of the section will feel stale even when the reference pages are current.

Check navigation and search after structural changes​

If you moved pages between categories, renamed slugs, or changed page titles:

  • review sidebars.ts
  • rebuild the site
  • search for the old and new phrases locally
  • confirm the intended pages still win in the results

Close with a focused handoff​

A strong handoff tells the next maintainer exactly what changed:

  • which repo triggered the docs refresh
  • which pages were updated or resynced
  • which commands and links were verified
  • which open questions still remain, if any

Next steps​