Review existing specs about specs HOT 7 CLOSED

In no particular order, a variety of specs

• ZCash Protocol Spec
• Ethereum Yellow Paper
• RFC 7049 - CBOR
• ECMA 262 (JavaScript)
• RFC 4880 - PGP

from specs.

• IPFS Specs

from specs.

@nicola IPFS specs are good to look at, but I believe that they are not at the level of completeness and polish that we would want for our upcoming work, just as a note.

from specs.

Some thoughts I have collected while reading and implementing specs in the past.

Give good examples

Giving good examples for things like binary formats or data structures are invaluable
for anyone trying to implement the spec.

Give context

Explain why what is being described is in the spec. For someone reading the spec and trying to understand the whole system is important to know why things are where they are.

Avoid ambiguity at all cost

It is very easy to write something and think this should be clear to the reader, but it turns out it is not at all. This can be especially problematic when things like data structures or algorithms are described in prose, without examples and diagrams.

Diagrams and pseudocode are great

Use them to your adventage, but make sure to explain them well.

Other specs

DRY writing is good in the spec world as well, but if other specs are refereneced they need to be versioned very exactly. Otherwise the referenced spec might change even though what this spec expects did not.
If there is no versioned version of the spec you want to reference available, consider including it in the appendix or maintain a copy of it that you are referencing.

No marketing

Do not try to sell me on your idea! This is a spec, not marketing material. The ideas and concepts should be described and choices explained why they were made. But at no point should there be attempts of marketing something to the user.

No unecessary prose

This is a spec, not a story book or your memoirs. Write and explain what is required to get the information across, but not more.

from specs.

• RFC 2813 IRC Spec

from specs.

Update from 10/31:

• @nicola has reviewed extensively
• team still needs to write down agreements & expand on notes from filecoin spec doc

from specs.

Some other specs I stumbled upon

• http://github.com/webassembly/design
• http://dwarfstd.org/doc/DWARF4.pdf

from specs.