<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom">
	<channel>
		<title>Studies on cotty</title>
		<link>https://nowa.im/cotty/research/studies/</link>
		<description>Recent content in Studies on cotty</description>
		<generator>Hugo</generator>
		<language>en</language>
		
		
		
		
			<atom:link href="https://nowa.im/cotty/research/studies/index.xml" rel="self" type="application/rss+xml" />
			<item>
				<title>Documentation practices in projects that publish specifications</title>
				<link>https://nowa.im/cotty/research/studies/2026-11-documentation-practices/</link>
				<pubDate>Sun, 22 Nov 2026 00:00:00 +0000</pubDate>
				<guid>https://nowa.im/cotty/research/studies/2026-11-documentation-practices/</guid>
				<description>&lt;p&gt;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.&lt;/p&gt;&#xA;&lt;h2 id=&#34;findings&#34;&gt;Findings&lt;a class=&#34;anchor&#34; href=&#34;#findings&#34; aria-hidden=&#34;true&#34; tabindex=&#34;-1&#34;&gt;&lt;/a&gt;&lt;/h2&gt;&#xA;&lt;p&gt;Every claim below is [official] unless marked otherwise: it was read on the project&amp;rsquo;s own site or in its repository on 2026-11-22.&lt;/p&gt;&#xA;&lt;h3 id=&#34;kitty&#34;&gt;kitty&lt;a class=&#34;anchor&#34; href=&#34;#kitty&#34; aria-hidden=&#34;true&#34; tabindex=&#34;-1&#34;&gt;&lt;/a&gt;&lt;/h3&gt;&#xA;&lt;ul&gt;&#xA;&lt;li&gt;The site is a user manual (quickstart, overview, FAQ, changelog and more) plus a section called &amp;ldquo;Terminal protocol extensions&amp;rdquo;. That section has 14 pages. Each page specifies one protocol and is written for authors of other terminals and programs.&lt;/li&gt;&#xA;&lt;li&gt;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.&lt;/li&gt;&#xA;&lt;li&gt;Requirements are written with lowercase &amp;ldquo;must&amp;rdquo; and &amp;ldquo;should&amp;rdquo;. The page carries a note &amp;ldquo;Added in version 0.20.0&amp;rdquo; and no revision history.&lt;/li&gt;&#xA;&lt;li&gt;The site is built with Sphinx and the Furo theme.&lt;/li&gt;&#xA;&lt;li&gt;No proposal process is visible. The pages appear to be edited directly (not verified).&lt;/li&gt;&#xA;&lt;/ul&gt;&#xA;&lt;h3 id=&#34;pi-by-earendil&#34;&gt;pi, by Earendil&lt;a class=&#34;anchor&#34; href=&#34;#pi-by-earendil&#34; aria-hidden=&#34;true&#34; tabindex=&#34;-1&#34;&gt;&lt;/a&gt;&lt;/h3&gt;&#xA;&lt;ul&gt;&#xA;&lt;li&gt;The pi-durable package has three layers of documents:&#xA;&lt;ul&gt;&#xA;&lt;li&gt;A README that works as a guide: a list of concepts, explicit rules, and more than forty runnable examples.&lt;/li&gt;&#xA;&lt;li&gt;&lt;code&gt;docs/spec.md&lt;/code&gt;, the specification. It has 7303 lines and begins &amp;ldquo;This document is normative&amp;rdquo;. Its first chapter is terms and invariants, and its last is non-goals.&lt;/li&gt;&#xA;&lt;li&gt;Separate design documents.&lt;/li&gt;&#xA;&lt;/ul&gt;&#xA;&lt;/li&gt;&#xA;&lt;li&gt;&lt;code&gt;packages/agent/docs/harness-v2.md&lt;/code&gt; 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:&#xA;&lt;ul&gt;&#xA;&lt;li&gt;a compatibility policy at the top;&lt;/li&gt;&#xA;&lt;li&gt;goals and non-goals;&lt;/li&gt;&#xA;&lt;li&gt;concepts and invariants;&lt;/li&gt;&#xA;&lt;li&gt;records, and traces that mark where a crash can happen;&lt;/li&gt;&#xA;&lt;li&gt;recovery;&lt;/li&gt;&#xA;&lt;li&gt;the API and the implementation;&lt;/li&gt;&#xA;&lt;li&gt;open questions, testing strategy, implementation sequence;&lt;/li&gt;&#xA;&lt;li&gt;required reading: an ordered list of files &amp;ldquo;for a fresh implementation session&amp;rdquo;.&lt;/li&gt;&#xA;&lt;/ul&gt;&#xA;&lt;/li&gt;&#xA;&lt;/ul&gt;&#xA;&lt;h3 id=&#34;earendil-rfcs&#34;&gt;Earendil RFCs&lt;a class=&#34;anchor&#34; href=&#34;#earendil-rfcs&#34; aria-hidden=&#34;true&#34; tabindex=&#34;-1&#34;&gt;&lt;/a&gt;&lt;/h3&gt;&#xA;&lt;ul&gt;&#xA;&lt;li&gt;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.&lt;/li&gt;&#xA;&lt;li&gt;The RFCs are short. Eight of them measured about 300 to 1900 words each, and they share no fixed set of sections.&lt;/li&gt;&#xA;&lt;li&gt;The series holds company principles and investigations as well as technical decisions.&lt;/li&gt;&#xA;&lt;/ul&gt;&#xA;&lt;h3 id=&#34;mcp&#34;&gt;MCP&lt;a class=&#34;anchor&#34; href=&#34;#mcp&#34; aria-hidden=&#34;true&#34; tabindex=&#34;-1&#34;&gt;&lt;/a&gt;&lt;/h3&gt;&#xA;&lt;ul&gt;&#xA;&lt;li&gt;Proposals are called SEPs. The template has an abstract, motivation, specification, rationale, backward compatibility, security implications and a reference implementation.&lt;/li&gt;&#xA;&lt;li&gt;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.&lt;/li&gt;&#xA;&lt;li&gt;A final SEP is frozen. Where the specification has since diverged, the specification governs.&lt;/li&gt;&#xA;&lt;li&gt;A script renders the SEP files into the documentation, and the automated checks fail when the rendering is out of date.&lt;/li&gt;&#xA;&lt;li&gt;The site is hosted on Mintlify, a commercial service.&lt;/li&gt;&#xA;&lt;/ul&gt;&#xA;&lt;h3 id=&#34;acp&#34;&gt;ACP&lt;a class=&#34;anchor&#34; href=&#34;#acp&#34; aria-hidden=&#34;true&#34; tabindex=&#34;-1&#34;&gt;&lt;/a&gt;&lt;/h3&gt;&#xA;&lt;ul&gt;&#xA;&lt;li&gt;Proposals are called RFDs. They move through Draft, Preview and Completed. Only Completed carries a stability commitment.&lt;/li&gt;&#xA;&lt;li&gt;Experimental work goes behind a feature gate named after the RFD.&lt;/li&gt;&#xA;&lt;li&gt;The site is hosted on Mintlify.&lt;/li&gt;&#xA;&lt;/ul&gt;&#xA;&lt;h3 id=&#34;matrix&#34;&gt;Matrix&lt;a class=&#34;anchor&#34; href=&#34;#matrix&#34; aria-hidden=&#34;true&#34; tabindex=&#34;-1&#34;&gt;&lt;/a&gt;&lt;/h3&gt;&#xA;&lt;ul&gt;&#xA;&lt;li&gt;Proposals are called MSCs. After the final comment period, a proposal waits in a state called &amp;ldquo;spec PR missing&amp;rdquo; until the change is written into the specification. That change must link to a working implementation.&lt;/li&gt;&#xA;&lt;li&gt;Before a feature is in a released version of the specification, implementations use unstable prefixes.&lt;/li&gt;&#xA;&lt;li&gt;The specification has released versions, v1.1 to v1.19, each with a changelog.&lt;/li&gt;&#xA;&lt;/ul&gt;&#xA;&lt;h3 id=&#34;from-general-knowledge&#34;&gt;From general knowledge&lt;a class=&#34;anchor&#34; href=&#34;#from-general-knowledge&#34; aria-hidden=&#34;true&#34; tabindex=&#34;-1&#34;&gt;&lt;/a&gt;&lt;/h3&gt;&#xA;&lt;p&gt;These were not checked this time.&lt;/p&gt;</description>
			</item>
			<item>
				<title>foot and other terminal emulators</title>
				<link>https://nowa.im/cotty/research/studies/2026-11-terminal-emulators/</link>
				<pubDate>Sun, 22 Nov 2026 00:00:00 +0000</pubDate>
				<guid>https://nowa.im/cotty/research/studies/2026-11-terminal-emulators/</guid>
				<description>&lt;p&gt;What is a current terminal emulator made of, and how do the common ones differ? foot shows how little one needs: a Wayland client, a CPU renderer and a font library, in a package under 1 MB. The common emulators differ in language, renderer and platform. Rendering is not an open problem in any of them.&lt;/p&gt;&#xA;&lt;p&gt;This note was first part of a longer note on what a terminal is. The argument of that note is now the post &lt;a href=&#34;https://nowa.im/cotty/posts/what-a-terminal-is/&#34;&gt;What a terminal is&lt;/a&gt;. The facts with a date stay here.&lt;/p&gt;</description>
			</item>
			<item>
				<title>Site generators for a bilingual documentation site</title>
				<link>https://nowa.im/cotty/research/studies/2026-11-docs-site-generators/</link>
				<pubDate>Sun, 22 Nov 2026 00:00:00 +0000</pubDate>
				<guid>https://nowa.im/cotty/research/studies/2026-11-docs-site-generators/</guid>
				<description>&lt;p&gt;Which generator should build the cotty site? Four were built against the same sample. By function, Starlight fit best. Hugo was chosen: it is one program with no dependency on the JavaScript package ecosystem, and what it lacks can be closed with our own templates and scripts.&lt;/p&gt;&#xA;&lt;h2 id=&#34;findings&#34;&gt;Findings&lt;a class=&#34;anchor&#34; href=&#34;#findings&#34; aria-hidden=&#34;true&#34; tabindex=&#34;-1&#34;&gt;&lt;/a&gt;&lt;/h2&gt;&#xA;&lt;h3 id=&#34;method&#34;&gt;Method&lt;a class=&#34;anchor&#34; href=&#34;#method&#34; aria-hidden=&#34;true&#34; tabindex=&#34;-1&#34;&gt;&lt;/a&gt;&lt;/h3&gt;&#xA;&lt;p&gt;The sample was a set of paired English and Chinese pages taken from cotty&amp;rsquo;s own notes: a product page, an RFC with metadata, and a post. Links were written as relative paths to &lt;code&gt;.md&lt;/code&gt; files, the way a repository browser follows them. Each generator built the sample. Then errors were introduced: a missing translation, a link to a missing page, a link to a missing anchor, and an invalid metadata value.&lt;/p&gt;</description>
			</item>
	</channel>
</rss>
