Documentation - Intro

[curiecrypt]

Content

This PR aims to provide

• Introduction section of the documentation
• A page including the variable mapping
• README update

Pre-submit checklist

• Branch
  • Commit sequence broadly makes sense
  • Key commits have useful messages
• PR
  • No clippy warnings in the CI
  • Self-reviewed the diff
  • Useful pull request description
  • Reviewer requested
• Documentation
  • Update README file (if relevant)
  • Update documentation website (if relevant)

Comments

Run the following command to compile the documentation:

cargo doc --no-deps --open

Note that you might need to run cargo clean before compiling to see the changes.

Issue(s)

Closes #60

[rrtoledo]

Looks quite good!

Several comments:

• Nitpicking here and there. p.s. there is a "-" in non-interactive 😬
• You don't mention "lower bound" in the very beginning and stay quite general with not well defined terms ("evidence", "valid", "knowledge"...). I think the introduction would improve by being more precise (then when it is clear about what validity or an evidence or and so on are, you can use these terms everywhere). The first sentence must be straight to the point.
• Some points are repeated across different sections (you talk about decentralized system or blockchain in a few places, there is a "key application" at the beginning and applications section at the end...).

[rrtoledo]

I just discovered noninteractive in one word is also a correct spelling sorry! 🤦‍♂️
I do think we should use a "-" though here, especially when mentionning NIROPK which is an acronym (hence separate words).

[curiecrypt]

@djetchev, @rrtoledo, @tolikzinovyev

• docs/intro only includes a high-level overview of the protocol without touching anything specific.
• docs/varmap includes a table of variable names mapped to the versions in the paper. Please let me know if there are any mistakes or the ones that I forgot. Also, I linked the public variables to the definitions in the code. I just gave the variable names for the private ones since it is not possible to document the private objects unless we state otherwise. If we all agree we can generate the documentation for those as well. Last but not least, the links might be changed after the PR Add wrapper structure to work on #66 is merged.
• README includes generic information about the protocol with an example. (I wanted to keep the example as generic as possible but with your suggestions we can tailor it to the cases that we have.) The documentation link on README does not look like a link on GH readme page since we don't publish it on a real website yet. Although, you can see it as a link if you compile the documentation. As the library improves (as we add tests, benchmarks, and other versions) we will enhance the README to cover some test results or comparisons.

[rrtoledo]

First pass, on the readme only.
It looks really good! The only point I have is that privacy is not a feature of Alba, hence I put some comments to correct this.

[tolikzinovyev]

I did an initial pass. My first impression is that it's pretty good docs except some sentences could be more concise and precise. I would need more time to think carefully about what is missing and what is possibly redundant, and if there is a better structure.

Major request: could we have each sentence on each own line in the readme markdown? Right now when leaving review comments, you need to make extra effort to say which sentence it refers to. It's also difficult on the receiving side I imagine.

[curiecrypt]

I did an initial pass. My first impression is that it's pretty good docs except some sentences could be more concise and precise. I would need more time to think carefully about what is missing and what is possibly redundant, and if there is a better structure.

Major request: could we have each sentence on each own line in the readme markdown? Right now when leaving review comments, you need to make extra effort to say which sentence it refers to. It's also difficult on the receiving side I imagine.

@tolikzinovyev Thanks for the feedback and the suggestions.
I put each sentence in a single row for the README. It makes sense. However, I did not do it for the bullet lists of intro. It causes to divide bullets and it looks ugly. But, I guess it won't be a problem for the bullet items since they are not that long.

[tolikzinovyev]

The readme looks significantly better, thanks for the improvements! I left some minor comments there and reviewed intro.md.

[rrtoledo]

Looks good! I added a few comments and suggestions.
Feel free to disagree with my nitpicks, it was mostly to split long sentences in 2 (and sometimes to clarify).

[djetchev]

Great job!

[rrtoledo]

LGTM