How should I split docs updates into milestones for a documentation website?

Tares plans a project as milestones, each with acceptance checks, so split your docs updates by what a reader or reviewer can verify, not by page count. Each milestone ends with one question that brings you the choices the crew made on its own. A good split for a documentation website is a working base, then the content changes, then merged and live.

How it works

The software factory for Claude Code turns your spec into a plan of milestones. Each milestone carries acceptance checks and holds tickets. For each ticket, a builder makes a branch, does the work and opens a pull request. The reviewer posts a verdict, and once it passes and CI is green, the builder merges.

The milestone is also where your say comes in. When the crew meets something the plan does not cover, it picks the sensible answer, writes it down as an assumption and carries on. At the end of each milestone, the orchestrator brings you all of that milestone’s assumptions in one question. You keep them or change them, and your answer is recorded in the project’s Decisions fold in your own words.

So a milestone boundary is a checkpoint. The work in it is merged and reviewed, and the choices the crew made along the way are confirmed by you. The next milestone then starts from confirmed ground.

The A project, end to end page shows this on a real project with three milestones:

• M1, tests and CI on the branch.
• M2, payout history stays as it was.
• M3, merged and live.

Each one names an outcome you can check, not a list of files.

Set it up

1. Write each milestone as an outcome with acceptance checks that someone can answer yes or no. For a documentation website, a split along these lines works:
   • M1, the base builds. Navigation, page structure or templates are in place, and the site builds and CI passes on every pull request.
   • M2, the updated content is correct. The pages you are changing say what the product does now. Name the pages in the acceptance checks.
   • M3, merged and live. The pull request is documented, merged into main and the site is published.
2. Keep each milestone small enough that its assumptions fit in one question. If you expect many open choices, such as naming, page layout or what to cut, split the milestone so you can confirm them earlier.
3. Put anything that only you can decide into the spec, so the crew does not have to guess it. Run the spec in the repo and answer Claude Code’s questions. A second model challenges the plan, and Tares stores the spec, the plan, an AGENTS.md for the project and the milestones with their acceptance checks.
4. Bring up the crew and plan the project. If you are new to the factory, Get started covers the prerequisites, including a signed-in Claude Code and gh. On a local Tares the steps run in this order:

tares up
tares mcp --transport streamable-http
tares factory crew up
tares factory spec "what you want to build"

Run tares mcp in a second terminal. On Tares Cloud, run tares login instead of the first two commands. 5. Read the milestones on the project page before you say yes. The Tickets fold shows each milestone with its acceptance checks. Say yes to hand the project to the crew, and the orchestrator starts a builder for the first milestone. 6. At each milestone end, answer the assumptions question. To make an answer stand from now on, say so, for this project or for every project.

What you get

• A plan you can check. Every milestone has acceptance checks, so you know when it is done.
• Confirmed choices before the next stage. The crew’s own decisions arrive together at the milestone end instead of scattered through the work. Each assumption names the tickets it touches and the builder that made it.
• A record of the build. The project page keeps your answers in the Decisions fold, the assumptions in their own fold, and each ticket with its pull request and review rounds.
• Room for the plan to grow. If the reviewer finds smaller issues outside the ticket it is reviewing, the orchestrator can turn them into a new ticket inside the milestone. In the example project that added one ticket to the second milestone.
• A clear finish. After the last milestone, the orchestrator asks whether the project is finished. Your answer marks it Done.

When something else fits

• For a single small edit, such as fixing a typo or one paragraph, a one-milestone project is enough, or you can edit the page directly. Splitting adds a question at the end of each milestone that you may not need.
• If the real question is who builds it, the AI SRE pages do not apply. Tickets reach the crew through Tares, Linear or GitHub Issues, so choose the ticket source that matches where your team already tracks docs work.

Related