tlsnotary / docs-mdbook

TLSNotary Documentation created with mdBook
https://docs.tlsnotary.org
5 stars 11 forks source link

refactor Section 2 #13

Closed themighty1 closed 1 year ago

themighty1 commented 1 year ago

This PR refactors section 2 to give a high level overview of how the protocols work. Sections 3 and 4 are added and they contain the low level explanation of the Signing/Verification process.

As agreed, our goal is to keep Section 2 accessible to a person who tries to get a general understanding how the subprotocols work without overwhelming them with technical details.

For now, it's best if we ignore this PR's awkward choice or words, abbreviations, formatting, punctuations etc. and only make sure that:

When we establish the exact contents of each section, we will have another iteration where we can polish the wording.

pls use mdbook serve to view the book, since github's link navigation for .md is broken.

themighty1 commented 1 year ago
Do we want to use Prover instead of User?

I don't know. There is potential cognitive friction because those who have not spent enough time to grok how the protocol works may think that the Notary is actually the entity which proves/attests to data provenance.

My mdbook refuses to compile. Which version do you use?

The versions in the latest README fixes

I think it is beneficial to have a maximum column width of something like 80-100, which makes it easier to work with the text.

Is it only inconvenient when reviewing the text via gh interface? Requring running cargo mdbook to review is a lesser inconvenience imo vs introducing max. column width.

themighty1 commented 1 year ago

I think in the Notarization section we should avoid any mention of DEAP or other protocols > and instead refer to such as MPC. In other words, I think we can generally speak more high-level about how it works in this area of the docs.

Ok, we can try to only mention MPC, except in one place:

What about Handshake? What level of detail should go there? Do we say "we perform the TLS handshake in MPC" or do we break down and mention each subprotocol like currently done: MPC ECDH, MPC PMS, MPC key derivation?

@sinui0

sinui0 commented 1 year ago

What about Handshake? What level of detail should go there? Do we say "we perform the TLS handshake in MPC" or do we break down and mention each subprotocol like currently done: MPC ECDH, MPC PMS, MPC key derivation?

For this high-level sections, I do think that just handwaving with "we do this in MPC" is sufficient. We can break it down further in our more technical docs in subsequent sections. I see the target audience for the first sections, eg "Notarization", as those that just want to grok the bird eye view.

themighty1 commented 1 year ago

Now that we have an idea of the book structure, I incorporated all the feedback and pushed the resulting changes into the dev branch. We can continue working on the dev branch and open PRs against it. For some reason mdbook's links are off, I couldn't debug what was causing it.