How to Write Unprotocols
When you start to write an unprotocol specification document, stick to a consistent structure so that your readers know what to expect. Here is the structure I use:
Cover section: with a one-line summary, URL to the spec, formal name, version, who to blame.
License for the text: absolutely needed for public specifications.
The change process: i.e., how can I as a reader fix problems in the specification?
Use of language: MUST, MAY, SHOULD, etc., with a reference to RFC 2119.
Maturity indicator: is this an experimental, draft, stable, legacy, or retired version?
Goals of the protocol: what problems is it trying to solve?
Formal grammar: prevents arguments due to different interpretations of the text.
Technical explanation: semantics of each message, error handling, etc.
Security discussion: explicitly, how secure the protocol is.
References: to other documents, protocols, etc.
Writing clear, expressive text is hard. Do avoid trying to describe implementations of the protocol. Remember that youâre writing a contract. Describe in clear language the obligations and expectations of each party, the level of obligation, and the penalties for breaking the rules. Do not try to define how each party honors its part of the deal.
Here are some key points about unprotocols:
As long as your process is open, you donât need a committee: just make clean, minimal designs and make sure anyone is free to improve them.
If you use an existing license, you wonât have legal worries afterwards. ...
Get ZeroMQ now with the O’Reilly learning platform.
O’Reilly members experience books, live events, courses curated by job role, and more from O’Reilly and nearly 200 top publishers.
