Documentation Standards

This page defines the minimum writing standard for this repository. Use it when creating or editing any documentation page, whether the change is written by a human or generated with Codex.

1. Decide Public Or Internal First

Choose the page location before writing.

Use docs/public/ when the content is safe for anyone who can access the site:

• setup and onboarding
• product usage
• external integration notes
• stable concepts intended for external readers

Use docs/internal/ when the content is meant for maintainers or the team only:

• architecture notes
• delivery workflow
• internal operations
• access, policy, or environment details

If a page mixes both audiences, split it into:

• a short public page for shared facts
• a separate internal page for implementation detail

Do not solve audience ambiguity by making one page vague.

2. Naming Rules

Use lowercase kebab-case filenames.

Good examples:

• getting-started.md
• ai-writing-workflow.md
• cloudflare-rollout.md

Avoid:

• spaces in filenames
• version numbers in filenames unless the version is part of the product name
• generic names such as notes.md, misc.md, temp.md, or new-page.md

Page names should describe the page job, not the meeting or task that created it.

3. Page Template

Use this shape for most pages:

# Page Title

One short paragraph that states what the page is for and who should use it.

## When To Use This Page

- who this page is for
- what questions it answers

## Main Content

Use short sections with direct headings.

## Related Pages

- Link to the next page a reader should open

Not every page needs every section, but every page should have:

• one clear purpose
• a short opening paragraph
• direct headings
• links to adjacent pages when useful

4. Content Rules

Write for maintenance, not performance.

• Prefer direct statements over marketing language
• Keep paragraphs short
• Use bullets for procedures, decisions, and boundaries
• Keep one page focused on one topic
• Link instead of repeating the same explanation across multiple pages

Every page should answer one of these jobs clearly:

• explain a concept
• document a process
• define a boundary
• provide a checklist

If the page does not do one of those jobs, tighten it.

5. Updating Existing Pages

Prefer editing an existing page over adding a near-duplicate.

Before creating a new page:

• check whether the topic already exists
• check whether the topic belongs under an existing page section
• check whether the title is stable enough to survive future edits

Add a new page only when:

• the topic has its own stable purpose
• the page would otherwise become too long
• the audience or access level is different

6. Codex Rules

When using Codex to maintain docs:

• ask it to read related pages first
• tell it whether the change belongs in public or internal
• ask for focused edits instead of broad rewrites
• ask it to update navigation when a page is added or renamed
• run pnpm docs:build after the change

Do not ask Codex to invent:

• security policy details
• internal URLs
• environment-specific values
• architecture claims that have not been verified

7. Public And Internal Boundary Rules

Move the page to internal if it contains any of the following:

• internal system topology
• access control details
• operational runbooks
• internal tools or dashboards
• decisions that are not meant for external readers

Keep the page in public only if it can be published without review from a security or operations perspective.

If you are unsure, default to internal and later extract a shorter public version.

8. Review Checklist

Before merging a documentation change, confirm:

• the page is in the correct section
• the filename follows the naming rules
• the title matches the page purpose
• the page does not duplicate another page
• the sidebar still reflects the page structure
• pnpm docs:build succeeds

The repository should remain small, explicit, and easy to review.