iota-wiki
iota-wiki copied to clipboard
iotaledger
Feat/notarization tutorial
Description of change
Added a single-page tutorial to showcase tokenless data notarization aka proof-of-inclusion to the past Tangle.
Links to any relevant issues
No
Type of change
Documentation Enhancement
How the change has been tested
Wiki was tested locally
Change checklist
Tick the boxes that are relevant to your changes, and delete any items that are not.
- [ x ] I have followed the contribution guidelines for this project
- [ x ] I have performed a self-review of my own code
- [ x ] I have commented my code, particularly in hard-to-understand areas
- [ x ] I have tested the wiki locally and tested that all external links work
Just as a general note (and maybe as question to @aleksei-korolev and @lucas-tortora): I don't think we should use German capitalization of words in the Wiki. AFAIK in English only beginnings of sentences and names are capitalized, anything else is just lower case. Also IMO we should not emphasize terms, just explain them and use them, no need to make them bold (see https://wiki.iota.org/learn/contribute-to-wiki/reference/style/formatting#emphasis).
Not this:
A Prover wants to prove to a Verifier that a dataset or file was not altered...
But just this:
A prover wants to prove to a verifier that a dataset or file was not altered...
@jlvandenhout I incorporated your feedback in regards to capitalization and emphasizing terms in my last commit.
I don't quite like that this tutorial boils down to "copy/paste two intimidating blocks of code and run a few bash commands". Maybe a short rundown for each would encourage users to at least look into them. "This one parses a block from a text file and then sends a REST API request asking a node to verify it" or along the lines.
@aleksei-korolev I agree that it's not ideal, but on the other hand the code block only runs successfully as a whole. That's the reason why I put effort into clarifying the different steps with the console output, so the user can follow along what's going on. When you say rundown, do you mean more comments in the large code block, or rather splitting the larger code block into separate smaller ones? The latter would lead to the user having to copy multiple code snippets in order to get one executable file.
@adrian-grassl
The latter would lead to the user having to copy multiple code snippets in order to get one executable file.
Most of the code tutorials I used, use this technique. I think the purpose of a tutorial is not so much to get something running, but rather to get the reader to understand what is happening. Explaining what the next step is and why it is needed and then copying over the discrete piece of code that is associated with it is more explanatory then just copying over one large block of code I think.
@adrian-grassl I've meant a short paragraph of text before the code block which tells me what I am going to read now. This way it will be easier for me to follow the comments in the code. In normal text, we don't really need this because we use headers and paragraphs for quick navigation, but we don't have that with code blocks so we are forced to read it from up to down line by line.
"This script parses a block from a text file and then sends a REST API request asking a node to verify it"
This sentence lets you know what will be in the code block, so you can navigate it more easily. "Alright, that's the parsing part, I can skip over it, alright, here we construct the request and here we send it".
@jlvandenhout @aleksei-korolev I followed your recommendations for the previously larger code blocks in the chapters Create Notarization Script and Verify Notarization Script and separated as well as described them in smaller snippets.
Can you please give it a look and let me know, if it's what you had in mind?