Documentation - MdBook tracking issue

[TimonPost]

This issue describes all the sections the new MD-book will contain. It belongs to a bigger overall documentation project as described here: #861.

The draft book can be found here. I will create PR's for individual pages if they are done. If you think that something could be added or have any ideas for improvement you could share it in this issue. It isn't definitive but feedback is welcome.

Definitive List of topics

(selected means written, [#000] means it has a PR already. I have some local branches queued up.

• [Md Book setup #868] QUINN Introduction
  - Description: README page embedded.
  - Goal: will make the user familiarize with QUINN on a more abstract level.
• [Md Book setup #868] QUICK Introduction
  - Description: what is QUIC very short, non-technical analysis that
  - Goal: will make the user familiarize with QUIC on a more abstract level.
• Networking Introduction
  - Description: Introduction to various concepts within networking.
  - Goal: will make the user familiarize with concepts, the terminology used in networking.
  • Transport Guarantees (Definitions for important terms like ordering/sequensing/reliable/unrealiable)
  • Transport Protocols (Short introduction to IP/UDP/TCP and their usecases/limitations)
  • Problems of TCP
    • Head-of-line Blocking
    • Connection Setup Duration
• QUINN
  - Description: Detailed analyses of the QUINN protocol and several guidance examples.
  - Goal: will make the user familiarize with QUINN and its API on a more technical level, also it makes him aware of differences to other protocols.
  • Comparison to Other Protocols (laminar, rudp, raknet, network sockets (valve), netcode)
  • Cryptography
    • Let's encrypt for typical use.
    • Rcgen for testing and custom/DIY certificate authorities.
    • Easy-rsa for a DIY certificate authority.
      -[ ] Workarounds for non-DNS applications (see Support connecting to IP addresses #564)
  • Configuration
  • Initializing a Connection
  • Data Transfer
    • Unidirectional Streams
    • Bidirectional Streams
    • Application Datagrams
    • Inexpensive Streams

Ideas for possible subjects

• Common QUIC Idioms and Application Protocol Design Concerns
  • Unordered Messages
    streams-as-framing for unordered messages
  • Ordered Messaging
    via application framing in a single stream
  • Keep-alives and Idle timeouts
  • ALPN
• Dealing with Errors
  • User-oriented documentation on the various types of WriteError, ReadError, and ConnectionError
• Footguns/Gotchas
  • If you close a connection immediately after receiving a response, the peer can't reliably tell whether you actually received the response, i.e. its SendStream::finish call may spuriously fail
  • If you don't await Endpoint::wait_idle before your process exits, peers may sometimes miss your close messages and have to time out your connection instead
  • UDP buffer sizes for servers handling many concurrent connections
  • Incoming streams begin in-order but complete out-of-order, so concurrency must be employed to avoid head-of-line blocking

[Ralith]

A couple quick notes:

easy-rsa for a DIY certificate authority

This should be dropped in favor of rcgen. Actually, on second thought, I don't think rcgen has a convenient CLI (yet?) so it's probably worth mentioning them both and linking docs.

Streams - Application datagrams

We shouldn't describe these as a type of stream, though we should definitely discuss them and compare/contrast to unidirectional streams.

[TimonPost]

What would you propose as a topic name instead of streams?

[djc]

Maybe something like "Data transfer"?

(Note that your capitalization is pretty inconsistent here. I would prefer that we consistently just use "Single capital letter per title" rather than "Capitals For Every Word".)

[TimonPost]

Good point for when I am going to work on them. Those titles are still a draft and are mostly a copy of @Ralith proposal in the other issue. I created two lists one with topics that are definitive and a list with ideas. I will try to keep that first list as close to the real book index as possible.

[TimonPost]

Locally I have a branch ready for the Networking Introduction. I will be working on the Quinn section now. When this PR #868 is merged I can create a pull request for it because those chapters build up on each other.