Initial roadmap for the first couple weeks & glossary

[renepickhardt]

We have discussed and agreed upon that our initial roadmap should look like the following:

1. define terms for the book (happening in the glossary.asciidoc)
2. define topics for the book
3. define user stories (happening in ch01.asciidoc )
4. come up with a preliminary working draft for a structure / outline of the book.

I have just transferred the glossary from my solo attempt to write the lightning network book. I also merged it with the one from mastering bitcoin. there are many open stylistic questions which should be collected. also there are terms missing.

Additionally we need to define user stories (similar to the ones in mastering bitcoin) Maybe we could even extend some of the user stories from mastering bitcoin.

in any case input from the community for step 1 to 3 at this stage is very wellcome!

[super-e]

For point 3. a cool story would be the case of an online game similar to Candy Crush which has no advertisement/subscription and for which you pay for each move or for each perk/bonus you get.
Also a forum or twitter-like platform where for writing a comment you need to stake a certain (small) amount, and if your comments are of good quality you might get your stake back depending on how many likes you get, this should increase the quality of comments and discourage trolls.

[renepickhardt]

I have added a first version of chapter 01 in which I provided 6 user stories and tried to also respect the suggestions by @super-e. Feedback and requests are very welcome!

[super-e]

Some comments about the first sub-section of CH01:

• There is a lot of knowledge given for granted (What is Bitcoin, what is blockchain, why we wait for confirmations, what a software 'contract' is, what is Tor and onion routing, etc.) Is this intentional due to the intermediate-advanced level of the book or shall we re-calibrate? Either put this section in even a lower level for the ordinary Joe, or spend some words introducing those concepts, at least not giving them for granted
• The sentence that LN payments cannot be reversed is not 100% accurate, as if a node goes off-line and the counterparty broadcasts a previous state without counter-action (watch-towers etc.) then the payment IS reversed. Not sure here if we should go for rigorous statements or more light-handed
• I would spend few words to mention that unlike Bitcoin the payments need to pass hand between the nodes, 'hopping' through intermediate trustless participants before they reach the recipient, that would make the sentence about routing and the mention about forwarding make same more sense

Just my 2 sats :)
-E-

[MrBitcoinNorway]

I would like to contribute and was tinkling of my experience around raspiblitz the Raspberry Pi running Bitcoin / Litecoin full node and LN payment channels. However I am new to writing book content and especially her at GitHub and do not know where to start :( . I have read the contribution pages but still a bit lost.

[renepickhardt]

@MrBitcoinNorway I have just committed and pushed a tentative list of topics I was working on today. this includes a section about the raspiblitz. So at least from my side I would be very happy if you help writing a section about the Raspiblitz. We are still in the phase of figuring out what to include and what not. You could already start writing a section in the contrib folder (where as far as I understood @aantonop we collect contributions from the community before integrating them to the correct spots / places in the book.

I just added to the contrib guide another line how to clone your repo. I am not sure what makes you lost? Did you ever work with git? There are many tutorials if you search for them that explain how to:

• clone
• pull
• switch a branch
• add
• commit
• push

for reference:

git clone git_address_of_your_forked_repo
git checkout -b new_branchname
touch my_new_file.ascii
... # edit the file with the editor of your choice
git add my_new_file.ascii
git commit -m "explain us in a short summary what you did with your changes"
git push 

afterwards use the website github to make a pull request
if these are your issues please let us know we could try to clarify.

[renepickhardt]

• There is a lot of knowledge given for granted (What is Bitcoin, what is blockchain, why we wait for confirmations, what a software 'contract' is, what is Tor and onion routing, etc.) Is this intentional due to the intermediate-advanced level of the book or shall we re-calibrate? Either put this section in even a lower level for the ordinary Joe, or spend some words introducing those concepts, at least not giving them for granted

just added reviewing bitcoin as to the list of topics. I am not sure if this will be an appendix or even before the intro but I fully agree that this should be in the book even though we have mastering_bitcoin

• The sentence that LN payments cannot be reversed is not 100% accurate, as if a node goes off-line and the counterparty broadcasts a previous state without counter-action (watch-towers etc.) then the payment IS reversed. Not sure here if we should go for rigorous statements or more light-handed

something like this should probably be a separate issue in order to easier reference it.

• I would spend few words to mention that unlike Bitcoin the payments need to pass hand between the nodes, 'hopping' through intermediate trustless participants before they reach the recipient, that would make the sentence about routing and the mention about forwarding make same more sense

you could make a proposal directly in the text and create a pull request (:

[renepickhardt]

So the current plan for the structure is like this:

The book will target many different people but the primary audience are beginning developer and people with a CS bachlor (already while pursuing their degree)

Chapter 1 & 2 should be readable by everyone even without technical background. These chapters will help the developers to get introduced to the most important concepts and workflows of the lightning network and will help them with the more technical stuff.

Chapter 3 is the former chapter 2 (c.f. #67 ) it will give a high level overview of most components of the protocol and what the lightning network is already using technical terms but still omitting many details (which will be - with references to the BOLTs introduced in later chapters). One goal for chapter 3 is that a technically very sophisticated person should be able to understand all the important conpcepts and ideas and would be able to either now invent the lightning network on their own or be able to easily read the BOLTs.

After this overview chapter 4 will help people to get introduced and play with implementations.

Also each chapter should end with a list of questions that the reader should be able to answer and potentially with a few exercieses. It is not clear yet if that holds true for chapter 1 and 2.