# 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.)