Specifications

Having gone through the Tox specification today, and having gone through the XMPP RFCs in the past…it occurs to me that a specification is a complete and current description of a protocol, meant for implementers. But how often does an implementer actually implement a specification in its entirety, in the presented serial order?

Things like Orgdown or XMPP Compliance Suites might be a step in a better direction. You either write not one specification but many, starting from a simple one and progressing to a complete one, reflecting a suggested implementation order for a developer to follow. Or you write a separate document which does the same, but instead refers to sections of the final specification rather than maintaining many separate specifications.

A more radical way is to present the same data in different ways -

1. let the reader say, "I'm working on a client", to show client-relevant sections
2. let the reader say, "I'm working on a server", to show server-relevant sections
3. let the reader say, "I'm implementing X feature", to show client- and server-side sections relevant to that feature.

The common pattern is to have documents which are not merely skeuomorphs of paper documents with their static structure, but which have multiple and trivially-switchable structures, which also allow the user to transparently create their own structure. That sounds an awful lot like Xanadu.