Documentation system
On this page
This page defines how cotty’s documents are organized, what each kind contains, and the rules that keep them current. It is the normative description. RFC 0001 records why it is this way.
Two kinds of document
Documents rot when one page mixes two meanings of time. Every document here is one of two kinds:
- A state document describes what is true now. There is exactly one copy. It is always current and may be rewritten at any time.
- An event document records what was proposed, decided or found at a point in time. It carries a date. Once accepted or finished it is not rewritten; later events are added beside it.
Documents also belong to one of two spaces: the problem space (why, and what) or the solution space (how).
| State: one copy, always current | Event: dated, append-only | |
|---|---|---|
| Problem space | Product design | Version designs, research |
| Solution space | Architecture, specifications | RFCs |
| For outside readers | Specifications | Posts |
Rules
- Fold. An event document says why something changes. The change itself is made in the state documents, in the same commit. An RFC or a version design is not accepted until the state documents it affects have been updated.
- One home. Every fact is stated on exactly one page. Other pages link to it and do not restate it.
- Events are not rewritten, and state carries no history. After acceptance, an event document changes only in its status and in corrections of plain errors. A state document describes the present. Its metadata lists the RFCs that shaped it, and it says nothing else about the past.
- Designed is not implemented. State documents describe the accepted design. A page records the version that implemented it. Until then it is design only.
Where documents live
docs/
├── en/ English, the normative text
│ ├── product/ product design state
│ ├── versions/ one design per version event
│ ├── architecture/ internal technical design state
│ ├── specs/ protocols, formats, APIs state
│ ├── rfcs/ technical decisions event
│ ├── research/ landscape/, studies/, field-notes/ event
│ ├── posts/ essays event
│ └── handbook/ how the project works state
└── zh/ Chinese translation, same paths
site/ Hugo project: configuration and templates
tools/ check scripts
The directory decides the kind. No page declares its own kind.
Everything in docs/ is published on the site.
Kinds of document
Skeletons for each kind are in Templates.
Product design
Product design answers why the product exists and what it does. It lives in product/ and is a set of pages:
| Page | Content |
|---|---|
| Positioning | The problem, who has it, why now, what cotty is, why its parts are one design, what it holds to, what it does not do. It is about the problem and the product, not about the market or about competition. It states our own reasoning and names no other product. The analysis of other products is in research. |
| Scenarios | A few user roles and the core scenarios, written as concrete stories. Each scenario has a number and links to its evidence. Version designs and RFCs cite scenario numbers. |
| Principles | How trade-offs are settled. Each principle comes with an example. |
| Concept model | The objects a user sees, their relations and their states. Product and technical documents share these words. |
| Capability pages | One page per capability: the problem, the behavior as checkable statements, states, surfaces, what is out of scope. |
| Quality bars | Latency budgets, compatibility, privacy commitments. |
| Roadmap | Now, next, later. |
A page is added when its content has been designed. Status is draft until the design is agreed, then accepted.
Version design
A version design says what the next version changes in the product, and why. It lives in versions/ as vX.Y.md. Its scenarios are also its acceptance script. Status is planning, then active, then shipped. A shipped version design is frozen.
Product design changes through version designs. Technical design changes through RFCs.
Architecture
Architecture pages describe how cotty is built inside: components, data, invariants, failure and recovery. They live in architecture/. Nothing outside the project depends on them, so they may change whenever an RFC says so.
Specifications
Specifications are the contracts between cotty and other programs: protocols, formats, APIs. They live in specs/. They are written for people who implement them elsewhere, such as authors of agent CLIs and of other terminals.
RFCs
An RFC records one technical decision. See RFC process.
Research
Research records facts about the world as of a date. It lives in research/, in three folders:
landscape/: products and projects in this space.studies/: one question, investigated once.field-notes/: what happened in real use.
Research is never normative. Each note states the date its facts were checked, lists its sources, and labels how reliable each claim is: official, vendor, or third party. It ends with what the findings mean for cotty. A refresh is a new note. The old one stays, and gets one line that points to the new note.
Research is published, so that a reader can check what the state documents rest on. Two rules follow:
- A note about another project describes it and names its sources. Where the note judges, it says that it judges.
- A field note uses aliases for machines and people. It holds no addresses and no secrets.
Posts
Posts are essays for outside readers. They live in posts/. A post explains how we think; it does not decide. Decisions stay in the state documents and in RFCs.
Research and posts differ in where their value comes from. If the value of a text is its facts, it is research: the facts carry a date and sources, and a newer note refreshes them. If the value is its argument, it is a post: it speaks in our own voice, and it cites research for its facts.
Handbook
The handbook says how the project works. This page is part of it.
Languages
- Every page exists in English and in Chinese, at the same path under
docs/enanddocs/zh. Both are added and changed in the same commit. - The English text is normative. The Chinese text is its translation. Where they disagree, the English governs and the disagreement is a defect to fix.
- The two versions of a page have the same metadata except
title, the same heading structure, the same number of code blocks, and links to the same pages.
Conventions
Voice
Every page is published, so every page is written for a reader outside the project.
- Say what the thing is, how it works and why. State its limits, and say what is not decided.
- Use plain words. Leave out the language of selling and of competing: selling points, moats, winning, who copies whom.
- A page about cotty is about the problem and the product. Other products are described in research, as they are.
Metadata
Each page starts with a metadata block. It uses a small subset of YAML: key: value lines and lists of plain values.
| Field | Where | Meaning |
|---|---|---|
title |
every page | The page title. |
created |
every page except section pages | The date the page was first written, as YYYY-MM-DD. |
status |
product, architecture, specs, handbook | draft or accepted. |
status |
versions | planning, active or shipped. |
status |
rfcs | See RFC process. |
rfc |
rfcs | The RFC number. |
affects |
rfcs | The state pages the RFC changes, as paths below the language folder. |
rfcs |
state pages | The numbers of the RFCs that changed the page. |
implemented |
state pages, optional | The version that implemented the page. |
as_of |
research | The date the facts were checked. |
supersedes, superseded_by |
rfcs, optional | The number of the RFC replaced, or replacing. |
authors |
optional | A list of names. |
weight |
optional | The position of the page within its section. |
The date a page was last changed is not stored in the page. It comes from the version history.
Titles
The title is in the metadata. The body has no level-one heading and starts with text or a level-two heading.
Links
Links between pages are relative paths to the .md file, written inline. Such a link works both in a repository browser and on the site. An anchor is the anchor of the heading in the same language.
Section pages
Every folder has a landing page named _index.md. The name is required by the site generator.
File names
File names are lowercase with hyphens.
| Kind | Name |
|---|---|
| RFC | NNNN-slug.md, four digits |
| Research note | YYYY-MM-slug.md |
| Version design | vX.Y.md |
Diagrams
A diagram is written in mermaid, inside a mermaid code block. Repository browsers draw it, and so does the site. Where mermaid cannot express a diagram, use plain text inside a text code block, or an SVG file committed together with the source that produced it.
Checks
tools/check.py uses only the Python standard library. make check runs the checks on the sources and on the stylesheet. make verify also builds the site and checks the result.
Checks on the sources:
- Every page exists in both languages.
- Metadata is well formed, and each kind has the fields and status values it requires.
- RFC numbers are unique and match the file names.
- The two versions of a page agree in metadata, heading structure, code blocks and link targets.
- Every link between pages points to a file that exists.
- No body has a level-one heading.
- An accepted RFC lists the pages it affects, and each of those pages lists the RFC.
Checks on the built site:
- Every link between pages resolves to a page.
- Every anchor in such a link exists on the target page.
- No page loads a script, a stylesheet or an image from another host.
- Every script is a file served by the site. The structured data in each page is data, not a script, and must be valid.
Checks on the stylesheet:
- Each color reaches the contrast that Site design requires of it, in both themes.
- The colors in the stylesheet are the colors in the palette table of that page.
Site
The site is built with Hugo, a single program whose version is pinned in mise.toml. The templates, the stylesheet and the search script are in site/ and were written for this project. There is no third-party theme. How the site looks is defined in Site design.
The site is published at https://nowa.im/cotty/ by GitHub Pages, with English at the root and Chinese under /zh/. A workflow runs the checks on every push and publishes the main branch. A section appears in the navigation once it has a page.
Three rules keep the build chain small:
- The build installs nothing through a package manager.
- Pages load nothing from other hosts.
- JavaScript on the pages is allowed, and is written in this project. Code from elsewhere may be added only as a copy kept in the repository, with its version and its source recorded in
site/VENDORED.md. Each such copy is an exception that the maintainer approves. There is one: mermaid, which draws the diagrams.
Search runs in the browser. Hugo writes an index of every page for each language, and site/assets/js/search.js matches the query against it.
For search engines, every page carries a description, its canonical address, links to its other language and structured data, and the site has a sitemap. For language models, the site has llms.txt, an index of its pages, and llms-full.txt, its full text. Every page is also published as Markdown, at its address followed by index.md.
Not yet decided
- The license of the documents.