feedback: abrupt transition from high level content to fine details

[monkeypants]

Reading the spec from the top, the Introduction and then Goals section are very high-level, and the abrupt transition to fine-grained details in the next section (Use Cases) is jarring.

I suggest some bridging content that links the two sections - something that explains what I am about to read and why it is relevant to the high level content that I just read.

Specifically, because the document has four distinct topics (data model, validation, rendering and selective obfuscation), it would be great to explain that at a high level to prepare a structure in the reader's mind to hold the information that they are about to read.

[onthebreeze]

I think something like this would be nice in the introduction section

• some words describing the types of things that can be notarised and the business value of doing so (eg documents and deeds)
• The basic user workflow diagram that shows how the whole process works and why we have the separate parts of the spec - namely
  • A user has a document that they want to notarise and share - so they make an open attestation that describes it - hence the data model/ schema part
  • A user asserts their identity notarises the document - hence the notary interface part of the spec.
  • The user may wish to selectively obfuscate parts of the doc before sending it to a counter party - hence the selective disclosure section of the spec.
  • the counter party will want to verify the document - hence the verification part of the spec (i think this probably should be separate to the notary service part)
  • the counter party may wish to look at a human readable version of the doc - hence the distributed rendering part of the spec.

A diagram showing this flow and clearly relating parts of the flow to the corresponding parts of the specification would provide valuable context. And maybe it's 5 chapters not 4 - think about separating the notary action from the verification aciton?