zudo-doc
GitHub repository

Type to search...

to open search from anywhere

Maintaining Documentation Structure

Created Nov 6, 2026Updated Nov 20, 2026Claude

Add pages without eroding the category map — when to just place a page, when to review the structure, and how people and AI agents share one editorial policy.

Documentation sets drift one reasonable page at a time. This guide gives people and AI agents one shared procedure for adding content to a zudo-doc site while keeping its categories and the relations between pages meaningful. It is written for the projects that install zudo-doc, not only for zudo-doc itself.

The procedure has two speeds. An ordinary addition gets a short placement check and a one-line reason. A structure review starts only when there is evidence that the current categories no longer fit what readers need. Keeping the structure as it is counts as a successful outcome of a review, not as a failure to act.

Three Layers and Who Owns Them

LayerWhere it livesWho changes it
Common guideThis page, shipped with zudo-doc's documentationzudo-doc maintainers
Project editorial policyOne file in your project — AUTHORING.md in a new scaffold, or an existing file you designateYour project's owners
Instructions and skillsREADME.md, CLAUDE.md, AGENTS.md, and optional skillsYour project, pointing at the policy

The project policy is the single source of truth for your categories. README.md, CLAUDE.md, AGENTS.md, and any skill only point to it. Do not copy detailed category rules into several files: copies drift, and an agent that reads a stale copy will apply the wrong boundary with confidence.

When a Change Needs a Placement Check

Typo fixes, wording changes, and formatting fixes follow the normal writing rules. They need no placement check and no structure review.

Answer four questions when you add a page, add a new reader task or topic to a page, or change what a page is for:

  1. Who can do what with this content? Name the reader and the task, such as "a site owner can add a locale".

  2. Does an existing page already serve that role? Search titles, descriptions, and the category listings first.

  3. Why this category, and is there a competing destination? Name the boundary in the policy that decides it.

  4. Does this addition change what the category means? For example, a reference category that starts collecting tutorials.

When the answers are clear, place the content and report the reason in one line, for example: "Placed under guides/ as a task guide for site owners; no existing page covers locale setup." That is the whole procedure for most additions.

When to Start a Structure Review

Start a structure review only when the four questions surface evidence of one of these:

  • Category conflict — the content fits two categories equally, or none, under the boundaries the policy states.

  • Duplication — an existing page already serves the same reader task.

  • An independent cluster — several pages now serve a distinct reader task that the category was not defined for.

  • A findability problem — a concrete report or observation that readers cannot find something, or land on the wrong page.

Read progressively. Start from the category map (the sidebar tree or the directory listing) and the policy. Then read the bodies of the pages that are related, competing, or listed as exceptions. You do not need to read every page body, and you do not need to write a long audit report. If you only surveyed part of the site, say which part. Never report a partial survey as a full audit.

Comparing Options

Write the concrete reader problem first, in one or two sentences. Then compare the options that would solve it:

OptionFits when
Add to an existing pageThe new content serves the same reader task as that page
Improve while keeping the structureClearer titles, a category index intro, or a policy boundary note fixes the problem
Local reorganizationSplit or merge pages, or rename, split, or merge one category, because a distinct reader task needs its own home
Related links, an index, or another entry pointThe content is cross-cutting: one primary home plus links from the other places readers look

Pick among the options that actually solve the reader problem, and only then compare how much change each one needs. "It changes fewer files" is a tiebreaker, not a reason to skip a reorganization the problem needs. Equally, do not reorganize when an option that keeps the structure solves the problem.

Do not decide by page count, by how evenly categories are balanced, or by a score with no stated basis. Do not impose Diátaxis's four types or a topic taxonomy on a project whose policy does not use them; use the categories the project defined.

Ask the owners only when important editorial goals conflict and you cannot resolve the conflict from the policy, for example keeping a published URL versus moving a page to its correct category. Present the concrete options and what each one affects. Routine placements and changes the policy already permits need no confirmation.

Recording Category Meaning

Record in the policy only what a later author needs to make the same decision:

  • what each category contains, what it excludes, and how it differs from its neighbours;

  • important exceptions, such as a page that stays in an old category to keep its URL;

  • the reason for a reorganization that actually happened.

Label where each statement comes from. A decision was made by the project owners. A fact is stated in existing documentation or configuration. A hypothesis is an inference by an author or an AI agent that nobody has confirmed. Treat unfilled policy fields as undecided rather than guessing them, and do not promote an unconfirmed hypothesis into a permanent rule.

Do not record routine placements. Do not reorganize the same category again without new evidence. A re-evaluation of the same input should reach the same conclusion.

zudo-doc Constraints to Check

  • Filesystem navigation is the default. A directory is a category and its index.mdx is the landing page. When the wanted hierarchy differs from the directories, moving files is normally the first choice (How to Structure Navigations).

  • A logical reclassification is not the same as a file move. Moving a file changes its URL. Decide both separately.

  • URLs that must stay can be re-parented with an editorial or umbrella tree. These change only the paired header and sidebar. Breadcrumbs, the previous/next pager, search, the sitemap, and <CategoryNav> keep following the URL tree, so a sidebar change alone does not make them agree.

  • categoryMatch is one top-level directory, and a linked parent row stays a real category node. See Header Navigation and Sidebar.

  • Note trays stay flat. A note tray is a sequence such as a journal or a course. Many entries are not a reason to convert it into a topic tree; convert it only when readers need topic access that the sequence cannot give.

  • Locale roots come from configuration. Read docsDir and each locales.<code>.dir from zfb.config.ts. Version snapshots such as docs-v1/ are not locales; do not restructure them along with current content (Internationalization, Versioning).

  • Generator-owned content carries generated: true or is written by a generator such as Document Sources. Reorganize its source or its settings, not the generated files.

  • defaultLocaleOnlyPrefixes lists paths that intentionally have no locale mirror (Default-Locale-Only Prefixes).

  • draft and unlisted pages still count when you look for duplicates: draft pages are excluded from the build, and unlisted pages are built but hidden from navigation (Frontmatter).

Worked Examples

Each example names the input, the reasoning, and a short decision. The decisions are examples of reasoning, not a single correct tree.

InputReasoningDecision
A fourth deployment target page for a deploy/ category that already has three target pagesSame reader task (deploy to a host), the policy's boundary already covers itKeep the structure; add the page with a one-line reason
guides/ gains five pages about writing plugins for the site's API, while it was defined as end-user how-tosA distinct reader (plugin authors) with a distinct task; readers report they cannot find the plugin pagesStructure review: compare a new plugins/ category, a nested guides/plugins/ category, and an index page; choose by the reader problem, then by change size
reference/ also reaches twelve pages, all API reference entries of the same kindSame count as above, but homogeneous content with no reader problemKeep the structure; count alone is not a reason to split
A request to write "How to configure search" when guides/search.mdx existsSame reader task as an existing pageUpdate the existing page; no new page
A page about authentication that matters to both setup and API usageCross-cutting contentOne primary home (for example guides/authentication.mdx) plus related links from the API pages; do not copy the body
A notes/ note tray reaches 120 dated entriesThe tray serves sequential reading; nobody reports a topic-access problemKeep the note tray; consider tags or a topic index page if topic access becomes a real need
A page belongs in another category, but its URL is linked from external sitesCorrect category versus a public URLKeep the file; re-parent with an editorial tree if needed, and record the exception in the policy. Do not move generated, locale-mirror, or version-snapshot files independently
A typo fix in a page titleWording onlyNo placement check, no review
The same review requested again a week later with no new pages or reportsNo new evidenceKeep the previous decision; say that nothing changed

Adopting in a New Project

A project created with create-zudo-doc contains these files at the project root:

FileRole
AUTHORING.mdThe editorial policy template. Fill it in; unfilled fields are undecided
README.mdA short "Adding or reorganizing docs" section for people
CLAUDE.mdA "Documentation structure" section for Claude Code
AGENTS.mdThe same pointer for Codex and other agents that read AGENTS.md

All three entry points name the same AUTHORING.md, which also holds the four questions and the minimal procedure, so the basic workflow works offline and without any optional feature. When the claudeSkillsWriting feature is enabled, the zudo-doc-writing skill adds detailed navigation rules and reads the same policy. When the skillSymlinker feature is enabled, the generated documentation skill's update mode also reads the policy before it writes (Documentation Skill Symlinker). When the Codex Resources or Claude Code Resources feature is enabled, the contents of AGENTS.md and CLAUDE.md are also published on the site as resource pages.

Replace the placeholders in AUTHORING.md with your readers, scope, entry points, and category boundaries as you decide them.

Adopting in an Existing Project

No migration command is needed. Work through these steps:

  1. Inspect README.md, CLAUDE.md, AGENTS.md, any nested instruction files, and any writing policy inside your documentation.

  2. Choose one canonical policy. Reuse what exists: a CONTRIBUTING.md section, an AUTHORING.md, or a page in your published docs. You do not need to create AUTHORING.md or rename an existing file.

  3. Add only the missing reference sections. Search each file for the policy path first. If a file already points to the policy, leave it alone. If the project uses Codex or another agent that reads AGENTS.md and has no AGENTS.md yet, create one that contains only the reference section. Never overwrite an instruction file wholesale.

  4. Connect skills you use — a hand-written writing skill or a copied zudo-doc-writing skill — to the same policy path.

  5. Check the result: every reference names a file that exists, there is only one canonical policy, no two files point at each other as the policy, and no reference uses an old path.

Where the Canonical Policy Can Live

  • Outside the published content (AUTHORING.md or CONTRIBUTING.md). Readers of the site never see it. Agents read it directly from the repository.

  • Inside the published content, for example src/content/docs/contributing/authoring.mdx. Contributors can read it on the site. In CLAUDE.md and AGENTS.md, reference the source file path, not only the site URL, so agents reach the local source without a network connection.

Reference Snippets

Add a section like this to CLAUDE.md and AGENTS.md, replacing the path with your canonical policy:

## Documentation structure

Before adding a page, changing what a page is for, or changing a category, read
`AUTHORING.md` (the project's editorial policy). Check for an existing page with
the same role, the right category, and whether the change alters what a category
means. Typo, wording, and formatting fixes skip this structure check.

Add a section like this to README.md:

## Adding or reorganizing docs

Read `AUTHORING.md` before adding pages or changing categories. It describes who
the docs are for, what each category contains, and the steps for placing a new page.

Keeping It Current

These are separate operations; one does not perform another:

  • Updating the @takazudo/zudo-doc package updates the framework only. It does not touch AUTHORING.md, README.md, CLAUDE.md, AGENTS.md, or copied skills.

  • Generating a new scaffold writes the current templates once. Later template changes do not reach an existing project.

  • Updating a distributed skill means copying the newer skill into .claude/skills/ by hand, or re-running setup:doc-skill for the generated documentation skill.

  • Updating your policy is an edit to your canonical file, made by your project's owners.

When you move a category or the policy file, update the paths in README.md, CLAUDE.md, AGENTS.md, and any skill in the same change. Before applying advice from this page, check which zudo-doc version you use; features such as note trays and editorial trees require the version documented on their pages.

See Also

Revision History

ClaudeCreated: 2026-11-06T08:56:30ZUpdated: 2026-11-20T11:51:25Z

AI Assistant

Ask a question about the documentation.

Preview theme

Loading theme previews…