Document Structure

• General idea of what it does and why (overview)

<aside> ⚠️

What is the main point? What we want is to explain things in a rising level of complexity. This helps the reader get the general idea quickly and optionally dive deeper. Consider that not everyone can read every single document in Nomos' spec.

The key thing is that someone going to implement a protocol or review it can read it and understand it at different levels:

• A good grasp of how it works (protocol/construction)
• An in-depth understanding of every component (detail) </aside>

Specifications should follow this structure:

<aside>

• Introduction
  • Gives context, such as objectives, requirements, rationale, references (that will help to understand this, preferably internal), previous work…
  • If there are important conclusions (for example, if the document is preliminary research comparing protocols), it's desirable to mention the result here. A reader might just need that, not read or scroll the entire document.
• Overview
  • Explain the protocol or solution at a high-level, so the reader is better prepared to understand the construction details.
  • A general diagram of the steps, flow or components can be very helpful here.
  • An overview is good when reading it already gives you the key ideas without having to read the rest of the document.
• Analysis, Construction or Protocol
  • Elaborate the details of the protocol.
  • Use detail diagrams where useful.
  • If you use code, use Python only.
• Details (optional)
  • This section can be used to further elaborate some details that can be considered auxiliary to the main construction, to avoid overcrowding that section.
  • This is the right place for things like proofs, cryptographic constructions or complex subcomponents.
• Annex (optional)
  • Optional section for additional information that informs protocol, such as benchmarks, comparisons, references, etc
  • This is where external references should go, ie. references that help expand or add details in something that we don't need to explain in this document. </aside>

Style

• Correctly structure the text

  • Make proper use of Section hierarchy: start with H1, then H2, then H3, then bold text titles / paragraph header.
  • No large blocks of wall. This is like code: that is likely better broken into subsections.
  • Use callouts to clarify things without breaking the flow of the explanation.
  • Do not add a Table of Contents.

• Use uniform styling:

  • No extra line breaks anywhere.
  • Use headers to structure the information
  • Do not use foldable headers. Information that you want to hide should go as a separate document (probably as Preliminary Research)
  • No sync blocks. Use hyperlinking instead. Create only links to stable references: only other specs or permalinks to papers (no personal notes or blog posts).
  • Do not set the page to Full Width. Keep it narrow.

• Review grammar. Make use of the Notion AI if necessary to improve the writing (there is a specific option for this), this is immensely useful specially for non-native English speakers (nearly all of us)

• Readability and clarity. Make sure things are clearly understood. Things should be written so others in the team can understand things even if they are not working on the problem exclusively. To this effect:

  • Structure the document with an introduction and recommended reads
  • Provide a rationale and objectives, giving enough context to understand what the document is attempting to solve
  • Provide conclusions
  • Comments and questions are a great way to improve the document. If someone is asking something that isn't clear, that means that the response should be included in the document so future readers get that more clearly.
  • Make use of callouts to clarify some things, provide examples or important notices. But do not abuse them.
  • Use listings and enumerations where appropriate. If a listing of enumeration has only one element, very high changes that it's not really a listing or enumeration, so please just use normal text.

• If anything is pending, make it obvious, by adding TODOs, like this:

  TODO: make Nomos even greater

  <aside> ⚠️

  Or this

  </aside>

You can verify that the document is following the quality standard using your favorite AI tool. A prompt is available https://gist.github.com/alvatar/d6f0907d2b200e7e993f55a735242dab.