What is the right format and structure of the specs?

[maurelian]

This is a question about how we should be structuring the specs doc. There are basically two polarities that I can see us locating ourselves between.

On the one hand you have very minimal specs which have minimal prose. The focus of the content is on defining data structures and functions in pseudocode. Examples include the ethereum/consensus, and tendermint specs.

On the other hand is a more plain english description, which reads a bit more like a whitepaper. I think our current spec is closer to this side, though it will naturally evolve to contain more pseudocode overtime.

[andrewgordstewart]

Here's a draft of one of Magmo's recent specs, which seems like a mix between the two poles. I'd think about something like that, since code communicates things precisely but fails to explain the context.

[maurelian]

I like it, what stands out to me in particular is the amount of <code> formatted text in the overview, which IMO serves to make the prose more concrete.

[norswap]

@maurelian Very nicely put!

I don't think there's a right answer, it's more of a trade-off.

• Formal style
  • Less welcoming to newcomers
  • Doesn't always communicate intuitions and design rationales
  • Easier to navigate for people who already understand the design
  • Less risk of ambiguity
  • Shorter and less verbose
• Whitepaper-style
  • Basically the opposite of everything above :)

(It's still possible to have an unambiguous whitepaper or a dryer spec that communicates intuition, it just require more work and involves more friction.)

The Eth2 spec is an interesting example, because it has no less than 3 annotated versions. Ben Edgington's version is great at giving intuition on what the spec actually does, while Vitalik's version is great at giving design rationale. But the non-annotated spec does none of those things and that's a shame in my estimation.

I do thing we should strive to have our cake and eat it too, i.e. the spec should be:

• welcoming to newcomers
• communicate intuition and design rationales
• unambiguous
• everything else being equal, as short as possible

I do think it's possible to hit that sweet spot! I'm hoping the latest spec PR will be an example of that — it's both
shorter, includes pseudocode, and I think clearer (thanks proto for nudging me in that direction). @andrewgordstewart provided another good example (I think the dispute game spec is another great example by the way!)

I think where the discussion opens up is how to accomplish all these objectives. Sometimes it might be worth splitting things up (i.e. giving intuition, design rationales and hard precise specifcations separately), sometimes not. Probably something to be discussed on a case-per-case basis.

---

I do want to end this with a plea to accomodate newcomers by making the spec very understandable, which requires being much more explicit than we think we need to be.

The first reason to do this is that newcomers will give up fairly easily if they don't understand the spec. (On the other hand, a developer that already understands the design may gumble, but will survive the spec not being maximally convenient.)

The second reason, is that there is a tendency by talented and experienced people to under-index on how much people understand what they themselves understand. I'm already someone that likes detailed explanation, and I still had to learn this lesson while and teaching at uni.

This is perfectly captured by the academic trope that a professor's most popular lecture/article amongst his peers (in the same domain) is always the one he intended for an external audience with no background on the subject matter.

We have repeatedly stated that opening the specs up to the community was one of our goals (though I will say I did overindex on the importance of that objective vs delivering 1.0 in a speedy manner). As long as we do have that objective, I feel like I have to be the one making this plea, as I only recently learned about the system we work on, and the confusion is still fresh in my mind. (Also students remind me every year that learning does not come easily!)

[norswap]

Okay, another remark actually.

It's not the first time we discuss meta-engineer matters like this, and I feel like our conclusions haven't really bound us in any way so far. Which is completely alright, sometimes you need to do the work to figure out the best way to do the work.

It's very to get lost in the woods if we're not tethered to specifics. It's probably better to discuss "should we split the foobar spec in half" than trying to hammer out a "spec philosophy".

If we do still want a practical guiding light to help us resolve those practical discussions (which we'll have anyway), then something I will suggest is to identify particular tradeoffs, and pick points in these trade-offs. Then we can refer back to these principles in our discussions.

For instance, above I said there is sometimes a trade-off between "making things easier to undestand" and "making things more verbose", and we should make things easier to understand in this case. (Note that sometimes making things easier to understand involves being less verbose!)

[protolambda]

One spec style approach I like is the one used in discv5: https://github.com/ethereum/devp2p/blob/master/discv5/discv5.md Each sub-document has a somewhat different style, but optimized for the type of thing it covers (i.e. design rationale and packet format should not be forced into the same format)

Another extensive specs repo example is the libp2p spec: https://github.com/libp2p/specs and the gossipsub spec is one of the more complicated components described pretty well: https://github.com/libp2p/specs/blob/master/pubsub/gossipsub/gossipsub-v1.1.md

[Graciouseats]

Providing the code would be precise and may reduce repetitive questions. Writing out a few sentences on what the code does would certainly provide context. This would also help someone like me (the code alone… no comprender) when encountering a question, would be able to locate the answer. Just my $.02.