Make examples more consistent

[emschwartz]

The Simple and Ethereum Settlement examples have slightly different styles and we should try to make them more consistent.

Some of the notable differences:

• The Simple example puts all of the commands in shell scripts while the Ethereum Settlement example puts the code in the README. The advantage of shell scripts is that they can be run directly, while the disadvantage is that it's less nice to read through them than reading the markdown README file. Having both means we need to make sure the code and README stay in sync, which is a bit annoying.
• The Ethereum example gets the account balances directly from Redis while the other uses the HTTP API. We should definitely try to avoid calling the DB directly and instead encourage the use of the API, however it's slightly nicer to print the balance in line with the comment (as is done here) than to print the JSON {"balance":"100"} on the line after the comment.
• The Ethereum example suggests opening 7 terminal windows to run the different services, while the scripts in the other example run the services as forked processes and write the logs to different files. Opening 7 terminal windows is pretty excessive so I'd lean towards only requiring one, though that does make it more difficult to watch different processes happen simultaneously.
• The examples made in the settlement README.md's are hard to read due to how the POST parameters are added. We should move these to a file / improve formatting What do you think? cc @gakonst @bstrie @dora-gt @pgarg-ripple

[emschwartz]

Another question is whether the examples should build on one another or stand on their own. For example, we could run them in a series so that in the first you set up two nodes and send payments with no settlement, then add settlement, then add multi-hop. Thoughts?

[gakonst]

Opening 7 terminal windows is pretty excessive so I'd lean towards only requiring one, though that does make it more difficult to watch different processes happen simultaneously.

From a user's visual perspective IMO it's always more useful to first see all terminals together, each doing their thing. Once you're accustomed to the process you can start running processes in the background and redirecting to logs (as I do in the example scripts).

Another question is whether the examples should build on one another or stand on their own. For example, we could run them in a series so that in the first you set up two nodes and send payments with no settlement, then add settlement, then add multi-hop. Thoughts?

Commented on this here: https://github.com/emschwartz/interledger-rs/pull/184#discussion_r309515966

The Ethereum example gets the account balances directly from Redis while the other uses the HTTP API

Is done in https://github.com/emschwartz/interledger-rs/pull/184/commits/88f83fdf64c2da431ce55c8f913c03114a41d507

Shell scripts vs README

No preference, I use the shell scripts when debugging since it saves a lot of time instead of running commands manually, or writing a Rust test

[dora-gt]

I agree to that examples should have consistency and hopefully a strategy to educate the readers. The strategy might be related to the 2nd question.

I mean... we should have a strategy of "Why do we write these documents or for what?". For example, if the goal is "To make the readers understand how to integrate ILP into their apps", we might have to educate:

1. What ILP is
2. What Interledger.rs is
3. How Interledger.rs works
4. How 2 nodes work (single-hop)
5. How 2 nodes settle payments
6. How more than 2 nodes work (multi-hop)
7. How to connect to the test-net
8. etc...

The above is almost the same as the structure Evan proposed here. I think these should not stand on their own; they should be integrated and have consequent meanings towards the goal. I think it is more understandable.

Btw, if the goal is "To make non-engineers understand how to run their nodes", the strategy might be different from the above. We should choose the segment of readers.

[pgarg-ripple]

When we talk about examples, I personally like things spread out to help me understand the complete process. So here is my suggestion:

Shell script vs README

Depends on how technical the audience is. Personally, I like README because it gives me a better sense of every step involved, instead of just running a script.

The Ethereum example suggests opening 7 terminal windows to run the different services, while the scripts in the other example run the services as forked processes and write the logs to different files. Opening 7 terminal windows is pretty excessive so I'd lean towards only requiring one, though that does make it more difficult to watch different processes happen simultaneously.

I think it's ok to open 7 windows. The example is not trying to prove that the settlement works; we know it does :-) The purpose of this example is for users to understand and to see for themselves all the different processes that happen.

The examples made in the settlement README.md's are hard to read due to how the POST parameters are added. We should move these to a file / improve formatting

We can provide the parameters in a table, maybe?

Another question is whether the examples should build on one another or stand on their own. For example, we could run them in a series so that in the first you set up two nodes and send payments with no settlement, then add settlement, then add multi-hop.

I would prefer independent tutorials. We can probably provide links to the previous & next tutorial in the series.

As an aside, please keep the heading and sub-heading style consistent in both the examples. The 'Two Node' example capitalizes the first letter of each word and the 'Ethereum Settlement' example has sentence-style heading.

[emschwartz]

Re: shell vs markdown. We can actually get the best of both worlds with "literate programming". We should write all the commands in the markdown file (in bash codeblocks) and then we can make them runnable with a simple script like mdlp or lit. You can run cat README.md | ./lit.sh --before "#" --stdio | bash in order to execute all of the commands in the file. Those tools don't have any external dependencies aside from awk and sed so anyone running on a Mac or Linux wouldn't have to install anything extra.

:+1: on standalone tutorials. When I encounter something new, I'll often click on something other than the most basic example first.

[dora-gt]

I'd be happy to take this issue on and help with documentation.

Before start, let me clarify the concluded principles argued here. If I have misunderstood, please tell me.

1. Script examples
   • We adopt literate programming style, using mdlp or lit.
   • I'm not sure if this completely fits but I'll try (there may be some compromises).
2. "7 windows problem"
   • We dare to make readers open multiple windows in order to show what's going on.
   • It might be better to leave some options to run these in the background.
3. Post parameters
   • It seems not concluded yet.
   • I personally think .json is better if it is shown in README.md using literate programming.
4. Documentation style
   • We adopt standalone tutorials.

Also, I would like to make sure what standalone tutorials means. Is it like this?

• Step 1 Start a node
• Step 2 Peer nodes
• Step 3 Set up settlement engines

[emschwartz]

Sounds good, thanks @dora-gt for working on this!

:+1: on 1-4.

By "standalone tutorials", we mean that each one will start up the nodes it needs, peer them together, etc. This is instead of writing them such that you have to run through the first example in order to have the right setup to run the second example.

[dora-gt]

It seems that mdlp and lit extract code block into a single file (or stdout), so it might be not so handy in our case. We might want to produce separate multiple scripts from a single markdown file. I'll make a utility to do this.

[emschwartz]

I don't think that's necessarily a problem. If you want to walk through the example step by step, you would just run each of the commands yourself. You would use this tool to run the whole example all at once.

Also, I would use the option that doesn't write the files to disk but rather pipes the output to stdout so it can be piped directly to bash.

[dora-gt]

Hmm, I think the markdown files will have .shs and .jsons which should be also written out from the markdown files in the philosophy of literate programming. I think the tools can not handle this situation.

Or... do you prefer writing .jsons out using echo in the scripts? It might not look nice.

In addition, indeed using pipes seems useful but if we use it, logs will be really hard to look. If we output logs into the other files, the readers eventually can not understand what's happening.

So I thought we needed a tool to output scripts in separate files.

[dora-gt]

My image is like this: https://github.com/dora-gt/mdlp-rs

See this example and you may be able to understand what I mean: https://github.com/dora-gt/mdlp-rs/blob/master/examples/example1.md

[dora-gt]

I tried to modify READMEs to make it consistent and realized there still are some problems...

If we write all the scripts in markdown files as literate programming, either of the following occurs.

• If the scripts are specified to output logs into log files so that the scripts can be run by lit or something, readers cannot understand what's happening when they copy&paste the scripts because the logs are written into the separate files.
• If the scripts are NOT specified to output logs into log files, the screen would be really hard to read when we use lit.

I also tried to embed independent scripts into markdowns using mdlp-rs but I realized that it doesn't look so nice because they have shebang and printf which look a bit weird.

So... I propose this solution. Amending the principle:

1. "7 windows problem"
   • We dare to make readers open multiple windows in order to show what's going on.
   • It might be better to leave some options to run these in the background.

to

1. "7 windows problem"
   • We assume readers to open only 1 window and output logs into separate logs.
   • That said, we educate the readers about how to tail the logs.

With this, we will be able to embed scripts in markdowns and use lit with pipes.

[emschwartz]

@dora-gt's proposal works for me. @gakonst @pgarg-ripple any objections?

[pgarg-ripple]

Works for me; no objections.