Consider removing most of the code from the BIP markdown

[jonasnick]

@real-or-random and I discussed a potential restructuring and refocussing of the BIP.

The BIP audience can be roughly categorized into three types (in the real world readers are usually a mix of the three):

1. implementors of the BIP
2. users of the "API" of the BIP
3. people who want to understand why the spec does what it does

Type 1 readers can just read the current BIP from top to bottom. I don't think they benefit much from the presenting the building blocks first.

Type 2 readers are probably overwhelmed by the current presentation. On the other hand, they should probably just read the API docs of the library they are using.

Type 3 readers benefit most from the current presentation. But there's also not much prose we can or want to write to really explain the SimplPedPop building block for example.

One possible perspective is to view the BIP markdown as a place that should not contain code without explanation.

Idea for restructuring:

• Start explaining just the function signatures of ChillDKG and how they're supposed to be used (e.g. diagram).
• Keep all code in the python files. This would mean for example that we do not need to explain the functions and classes in the prelim section separately from the reference code.
• Add section for more detailed explanation: for example, where SimplPedPop is from and the minor changes to it, the layered approach, the security arguments (e.g.: why the one-time pad works). Maybe we can do that using code snippets.

I'm not fully convinced that this is a better structure, but worth keeping in mind and revisit later.

[real-or-random]

The truth is that (almost) noone will read the document from top to bottom. People will skim, and then perhaps pic a specific section and read it in more detail, etc.

So whether we move the code out of the main document or not, it may be a good idea to restructure the sections with the three audience types in mind. For each section, at least we should have a clear idea which types it is supposed to cover. We may or may not make this explicit then. For some sections, this could be explicit in section headings (like "Implementation Considerations"), or we could even write it down in a short section after the intro, like "If you want to implement the BIP, read sections foo and bar [...]".

This will probably result in the code ending up in a separate section. And then it likely makes sense to move it out of the main doc, but we could decide later.

[real-or-random]

The code was removed in #21, and the recent 04b21601f85a6f86168f3483e82092aed6ad60b8 tried to make the purposes of the sections even clearer:

1. Intro (overview for everyone)
2. Internals (if you want to understand and implement the protocol)
3. Interface and usage (if you want to use the protocol)

It may make sense to swap 2 and 3; we can see later.