# Documentation practices in projects that publish specifications

Address: https://nowa.im/cotty/research/studies/2026-11-documentation-practices/  
Created: 2026-11-22

How do projects that publish protocols and proposals keep their documents usable? The ones that stay readable keep a living specification and fold accepted proposals into it. The depth is in the living documents. Proposals are short, or frozen once accepted.

## Findings

Every claim below is [official] unless marked otherwise: it was read on the project's own site or in its repository on 2026-11-22.

### kitty

- The site is a user manual (quickstart, overview, FAQ, changelog and more) plus a section called "Terminal protocol extensions". That section has 14 pages. Each page specifies one protocol and is written for authors of other terminals and programs.
- The keyboard protocol page opens with the problems of the status quo. Then come a quickstart, an overview, progressive enhancement, detection of support, and the legacy encoding. It lists the terminals, libraries and programs that implement the protocol.
- Requirements are written with lowercase "must" and "should". The page carries a note "Added in version 0.20.0" and no revision history.
- The site is built with Sphinx and the Furo theme.
- No proposal process is visible. The pages appear to be edited directly (not verified).

### pi, by Earendil

- The pi-durable package has three layers of documents:
  - A README that works as a guide: a list of concepts, explicit rules, and more than forty runnable examples.
  - `docs/spec.md`, the specification. It has 7303 lines and begins "This document is normative". Its first chapter is terms and invariants, and its last is non-goals.
  - Separate design documents.
- `packages/agent/docs/harness-v2.md` is a design document of 1655 lines. It was rewritten as a whole, and the commit message says that it supersedes the earlier document and what changed. Its structure:
  - a compatibility policy at the top;
  - goals and non-goals;
  - concepts and invariants;
  - records, and traces that mark where a crash can happen;
  - recovery;
  - the API and the implementation;
  - open questions, testing strategy, implementation sequence;
  - required reading: an ordered list of files "for a fresh implementation session".

### Earendil RFCs

- Earendil publishes RFCs at rfc.earendil.com with four-digit numbers. Its RFC 0001 defines the states draft, discussion, published, accepted and abandoned. A superseded RFC names its replacement.
- The RFCs are short. Eight of them measured about 300 to 1900 words each, and they share no fixed set of sections.
- The series holds company principles and investigations as well as technical decisions.

### MCP

- Proposals are called SEPs. The template has an abstract, motivation, specification, rationale, backward compatibility, security implications and a reference implementation.
- When a SEP is accepted, the same pull request must add the specification text, the schema changes and a changelog entry. To become final, a SEP also needs a reference implementation and a conformance test that maps each requirement to a check.
- A final SEP is frozen. Where the specification has since diverged, the specification governs.
- A script renders the SEP files into the documentation, and the automated checks fail when the rendering is out of date.
- The site is hosted on Mintlify, a commercial service.

### ACP

- Proposals are called RFDs. They move through Draft, Preview and Completed. Only Completed carries a stability commitment.
- Experimental work goes behind a feature gate named after the RFD.
- The site is hosted on Mintlify.

### Matrix

- Proposals are called MSCs. After the final comment period, a proposal waits in a state called "spec PR missing" until the change is written into the specification. That change must link to a working implementation.
- Before a feature is in a released version of the specification, implementations use unstable prefixes.
- The specification has released versions, v1.1 to v1.19, each with a changelog.

### From general knowledge

These were not checked this time.

- Rust keeps RFCs and, separately, the Reference.
- TC39 proposals carry specification text and are merged into ECMA-262.
- The IETF only appends. The definition of TCP ended up spread over many RFCs, and RFC 9293 was written to consolidate it.

## What this means for cotty

- Keep living documents and fold accepted proposals into them. This is the fold rule in [Documentation system](https://nowa.im/cotty/handbook/documentation/).
- Put the depth in specifications and architecture pages. The bar for a specification page is a kitty protocol page. The bar for an architecture page is pi's harness design.
- Keep RFCs thin: the decision and the reasoning.
- Take three practices from the others: only parts marked stable carry a compatibility commitment; the specification governs over the proposal; and, once there is code, each requirement maps to a test.
- Write for implementers and for coding agents. A list of required reading tells a new session where to start.

## Sources

- kitty: [documentation](https://sw.kovidgoyal.net/kitty/), [keyboard protocol](https://sw.kovidgoyal.net/kitty/keyboard-protocol/)
- pi: [pi-durable README](https://github.com/earendil-works/pi/blob/main/packages/durable/README.md), [harness-v2 commit](https://github.com/earendil-works/pi/commit/4f0437e2d58d651dd934119ecabea2893975f62f)
- Earendil: [posts](https://earendil.com/posts/), [RFC archive](https://rfc.earendil.com)
- MCP: [SEP guidelines](https://modelcontextprotocol.io/community/sep-guidelines)
- ACP: [RFD process](https://agentclientprotocol.com/rfds/about)
- Matrix: [specification proposals](https://spec.matrix.org/proposals/)

## Not covered

- The processes of Rust, TC39 and the IETF in detail.
- Python PEPs, Kubernetes KEPs, Wayland protocols and Tor proposals.
