halo2 icon indicating copy to clipboard operation
halo2 copied to clipboard

Add an explanation to the book about its structure

Open str4d opened this issue 2 years ago • 0 comments

The book is trying to cater to several groups of people simultaneously:

  • Developers who just want to use halo2 to write circuits, should only need to read sections 1 and 2, and then the crate documentation.
  • Section 3 is for people who want to understand the Halo 2 proving system itself, and how it works. It assumes a baseline understanding of how elliptic curves work, and some general cryptographic principles.
    • It doesn't currently explain particularly well why it works, as in "why would we build it in this way". I expect it makes some logical leaps that aren't obvious to someone who hasn't been reading zk-SNARK literature.
  • Section 4 is for people who want to understand Section 3 but don't have the necessary background knowledge.

The current book order is influenced by the order in which we needed to cater to the above groups of people during the development of halo2. But to someone who sees "book" in the title and assumes it's a traditional linear-order book, it's a very confusing order; section 4 would be more of an appendix in that case.

We should add a section to the start of the book explaining the above, and indicating that it's not a traditional linear-order book. We should also add more explicit forward references at the start of sections (particularly Section 3) where we think the reader will need to read a different section first.

str4d avatar Jan 26 '22 01:01 str4d