search

ethereum-optimism / optimistic-specs

Optimistic: Bedrock, is a protocol that strives to be an extremely simple optimistic rollup that maintains 1:1 compatibility with Ethereum
MIT License
168 stars 36 forks source link

Standardize presentation of parameters and data structures #252

Open maurelian opened 2 years ago

maurelian commented 2 years ago

Looking at the current state of the spec documents from a high level, they do not feel consistent in how the various parameters and data structures are presented. This is a result of having preferred to create an approachable prose driven style vs. a more bare bones approach like the Beacon Chain, which is a valid approach but it has the downside of being more difficult to skim for critical definitions.

I think we should shift towards a structure that makes params and types more prominent, and more consistent in their presentation.

Proposal

  1. Review all specs docs.
  2. Add a Definitions section immediately after the intro with the following sections (as needed):
    1. Parameters
    2. Type Aliases
    3. Data Structures

Some examples to follow include:

norswap commented 2 years ago

Personally I'd like to see an explanation as to why this is so useful, because I just don't see it.

It's a bit dispiriting to start a document with a long list of definitions for which you have absolutely no context. It's only useful once you already understand the specification and just need to look up things.

If furthermore, these definitions are not repeated at the point where they are explained, this organization actively hampers understanding, as one has to navigate back and forth (or not).

I'd also say that while Ethereum does indeed do it like that, a lot of other specifications (including the yellowpaper and most specs I've read, mostly in the domain of compilers and networking) don't do it this way. I think I can't think of another one (though I'm sure it exists).

A "reference" section (at the end) or document with only definitions might be useful however (and indeed, you do find this in serious specs, e.g. the Java language specification has an appendix with a consolidated grammar, which is otherwise spread out throughout the spec). If we should do this, we need to be wary of duplication (maybe find some way to automatically include text snippets from a single source).

maurelian commented 2 years ago

It's a bit dispiriting to start a document with a long list of definitions for which you have absolutely no context. It's only useful once you already understand the specification and just need to look up things.

Exactly :)

The spec has at least two audiences, implementers and everyone else. I think this kind of section is especially useful to implementers, but also auditors once they've already read the spec to get context.

A "reference" section (at the end) or document with only definitions might be useful however...

I'm fine with moving this content to the end of the document. Would that work for you, or are there other changes to its presentation you'd suggest?

norswap commented 2 years ago

I'm fine with moving this content to the end of the document. Would that work for you, or are there other changes to its presentation you'd suggest?

I think I'd like the structures introduced throughout, and then copied at the end, to avoid a very tedious act of jumping back and forth. It's a bit more work to maintain, but it's much better for the reader. Would that be acceptable?