InterPlanetary Standards Edited and Integrated to Travel Yonder (IPSEITY)

ipseity: The quality of being oneself.

This document seeks to improve our standards posture across everything. I'm stealing some thoughts from @lidel and expanding on them. Right now, we have standards scattered somewhat all over:

• https://github.com/ipfs/specs
• https://github.com/libp2p/specs/
• https://ipld.io/specs/
• https://github.com/multiformats/cid
• https://github.com/multiformats/multiaddr
• https://github.com/multiformats/multibase/

There is no single place to find them all, no unified way to write them, no built-in cross-referencing, etc. Too much is left to tribal knowledge and to copying local conventions.

Requirements

These requirements are provided for discussion. I am not yet an active member of the relevant communities and have not contributed to these standards, so I am both likely and happy to be wrong in my assumptions.

Single Publication Location. All of the published specs should land at a single location, eg. https://specs.ipfs.tech/. This should not necessarily require all of the current document to move, either the source or the existing links. We can set up GitHub actions or hooks that can read the current docs and publish them all in the right places. Having said that, if we rely on markup features that extend beyond vanilla/GH MD, the existing publishing pipelines will require some changes.

Easy Editing. Specification DSLs can be quite powerful but as we all know with great power comes a lot of documentation that you have to read. Markdown enhanced with a small number of features should prove enough and, I believe, matches relatively closely the current practices. Alternatives include using just basic MD at one end of the spectrum, which might limit things like metadata and cross-referencing, and a more advanced HTML-based DSL at the other end, which I suspect would be too much of a learning curve in many cases.

Simple Editing Tooling. I am working on the assumption that writing a spec will rarely be the primary pursuit of whoever is writing it. It will be done to support specific development, to document, to discuss. As such, the tooling should require close to no thinking beyond the initial install. Something like ipseity --watch foo.md will watch the MD for changes and open a browser tab to see the generated output that auto-refreshes and that displays errors. ipseity --out foo.html foo.md should generate. And ipseity --lint foo.md should run checks that can be used in CI/CD.

Cross-referencing. Specs often need to reference either entire other specs or specific notions defined in other specs. From the perspective of spec readers, it is often frustrating to see trying to track down a concept that is being used without knowing where it is from, and in that making sure that definitions are properly cross-linked is essential. But, conversely, that is extremely painful to manage for spec writers. The best way to address this is through some simple conventional markup that can create definition and link to them easily without having to remember much or even paying too much attention to namespacing (where possible). In the W3C/WHATWG world, this has been managed through the https://www.specref.org/ tool (for references to complete bodies of work) and the https://respec.org/xref/ tool (for definition cross references). Setting this up right is slightly involved but, I believe, pays for itself. The most difficult part is referential integrity: how to handle the case in which one spec removes a definition that others rely on.

PR Preview. It can be a lot easier to review a fully rendered document than a diff. In order to do that, PRs that involve specs should be able to automatically generate PR previews as well as diffs, and link to them. A good example of this is https://github.com/tobie/pr-preview.

Unified Review & Lifecycle Process. Having a common vocabulary and process for specs that is shared across a broad community is ideal. I would not suggest that we adopt the W3C's (it is too involved for this, and a lot of it is based on IP considerations). This isn't entirely separate from a unified store for the specs because it is part of the versioning strategy. (It may also inform some visual cues in specs, but that's minor.)