Documentation - tracking issue

[TimonPost]

For a study exercise, with the agreement of @djc and @Ralith, I will spend 84 hours on this project. Those 84 hours will be filled in by various documentation related tasks. This issue tracks the work that will be performed and can also serve as a place for discussion. Proposals for documentation-related tasks are welcome, I would like to gather ideas on what we want to improve and write. Code examples, GitHub book, videos, are all valid proposals.

Planning

• [x] Readme [#866] (6+ hours)
• [ ] MD-book [#865] (~21 hours)
• [ ] Code Examples [#890 ] (~21 hours)

Ideas

Motivations

• This library should be easier to get started with
• This library should look more professional by having a nice book and a nice entry read me with a logo and short information.
• There should be more examples of specific behavior and or use cases.
• There should be a book elaborating one some subjects for this libary.

[SriRamanujam]

User-oriented documentation on the various types of WriteError, ReadError, and ConnectionError would be very valuable. Often times when the library throws an error back to me, I find myself looking through the code to figure exactly what conditions would trigger a particular error type. Something along the lines of "If you see WriteError::Stopped(0) when writing to a send stream, then that almost certainly means the receive stream has been dropped or explicitly closed" would be enough to save me a lot of time digging through the library internals.

[Ralith]

We could also use some larger and more realistic examples, to illustrate and support discussion of good patterns. For example, a client/server chat system could demonstrate concurrent use of multiple streams, in-stream message framing, and shared state on the server, among other things.

[TimonPost]

NIce! I added the points to the list. So @Ralith @djc, I am thinking about the getting-started page. I have some ideas on this, we can use GitHub pages and to write a very nice visual documentation for this library. Also, I want to move the buffers and certificate section from the readme to the getting started such that the README will be simpler.

What kind of topics would you like to see documentation on in the getting-started/usage book?

[djc]

I've previously used mdbook in Askama, and it seems to be pretty nice and simple to build more structured and complex documentation. Askama also already has GitHub Actions workflow you can copy to set it up in GitHub Pages.

[Ralith]

What kind of topics would you like to see documentation on in the getting-started/usage book?

Some ideas, based on what I find myself explaining to people:

• Compare/contrast QUIC with TCP
• Cryptographic setup
  • 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 https://github.com/djc/quinn/issues/564)
• Common QUIC idioms and application protocol design concerns
  • streams-as-framing for unordered messages
  • discussion of how inexpensive a stream is
  • ordered messaging via application framing in a single stream
  • when to use unidirectional streams vs. bidirectional streams vs. application datagrams
  • keep-alives and idle timeouts
  • ALPN
• Application protocol design case studies
• 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
• Performance tuning

[djc]

let's encrypt for typical use, rcgen for testing, easy-rsa for a DIY certificate authority

Note that rcgen also supports building a CA certificate and certificate chain based on that, so that might be a more attractive option compared to easy-rsa?

[Ralith]

Oh, nice, didn't realize.

[TimonPost]

@djc I like your proposal to use md-book. Especially if we have code snippets in the documentation. Github pages can be nice if the documentation will not contain (rust) code. @djc so with Askama we can use templates for HTML, however, I am not sure if I see the customization use case yet. As far I can tell mdbook will fulfill our needs.

• We need a separate branch for gpages

• There is one issue. I want to move the buffers and certificate section from the readme to the book because the README should be simple. Also, I will want to add book references to the README. This is problematic because 1) the book should be published only after it is finished 2) The README like buffers and certificate section should not be removed until the book is published.

  My solution to this is to create a separate branch docs which I will be pushing my work too 'via PR's'. When I am done we can merge all the reviewed work to master. Then I will not be disturbing the public with my changes.

• If the above point is how we will do it can I get write access to this branch? Then, I don't have to create PRs for very minor quick fixes like a grammar fix or invalid link error. This will allow me to develop faster and you do not be disturbed by me making small fixes. Note that I am not talking about major changes because that should go via the PR-reviewing workflow imo.

• Lastly, ever considered a public github organization for QUINN?

[djc]

@djc I like your proposal to use md-book. Especially if we have code snippets in the documentation. Github pages can be nice if the documentation will not contain (rust) code. @djc so with Askama we can use templates for HTML, however, I am not sure if I see the customization use case yet. As far I can tell mdbook will fulfill our needs.

Not sure why you reference Askama here? I didn't mean that we'd need some customization based on Askama -- just that the Askama contains an example of how to set up an mdbook that you could use as a quickstart.

We need a separate branch for gpages

That should be straightforward to set up, and can be done as soon as it becomes necessary to publish the book.

There is one issue. I want to move the buffers and certificate section from the readme to the book because the README should be simple. Also, I will want to add book references to the README. This is problematic because 1) the book should be published only after it is finished 2) The README like buffers and certificate section should not be removed until the book is published.

Doesn't seem like a big issue. You should probably start with a PR making the proposed changes, that is, moving some of the content from the README into a newly created book (which can have just this content for now).

My solution to this is to create a separate branch docs which I will be pushing my work too 'via PR's'. When I am done we can merge all the reviewed work to master. Then I will not be disturbing the public with my changes.

I don't see much value in me creating a branch for you. You should just fork Quinn, start a branch in your fork, and create a PR based off of that branch as soon as it's ready for an initial round of review.

If the above point is how we will do it can I get write access to this branch? Then, I don't have to create PRs for very minor quick fixes like a grammar fix or invalid link error. This will allow me to develop faster and you do not be disturbed by me making small fixes. Note that I am not talking about major changes because that should go via the PR-reviewing workflow imo.

We do PRs for every change, however minor. For minor changes, the review process should be very quick, so the overhead is minimal anyway. Still, in the general case you probably shouldn't send a PR for one typo fix (although it's fine if that happens every once in a while).

Lastly, ever considered a public github organization for QUINN?

We've talked about it a little bit, but I at least wasn't sure what the cost/benefit ratio would be over the current setup. Is this relevant to the documentation setup somehow?

[TimonPost]

Not sure why you reference Askama here?

Sorry, was misinterpreting your original comment. However, now I understand that you spoke about your experience with it.

Moving some of the content from the README into a newly created book (which can have just this content for now).

If it would not directly matter for content to be away for ~1.5 months, then perfect 👍

Fast PR-reviewing

Nice, that would solve some of the burdens. I just want to prevent taking too much of your time if I make silly mistakes and need to update something. However, lets do it the ordinary way via forking then 👍

Github organization

It is not documentation related, though it is related to the public-facing aspect which I am trying to improve. The biggest reason is opinion-based, to me an organization makes a library look more professional (own URL, logo as pf foto). But also important is that the library will be owner-agnostic, in a way that if you leave or some other worst-case scenario happens, other people can continue working on it. Lastly, it allows multiple repositories to be part of the project Quinn. Take https://github.com/tokio-rs for example.

It is very easy to move the whole crate+issues+prs+all settings to a Github organization. It was just something I wondered about.

[djc]

If it would not directly matter for content to be away for ~1.5 months, then perfect 👍

No, I'm saying we would directly start publishing the book, even if incomplete, so the content is always available.

[djc]

It is very easy to move the whole crate+issues+prs+all settings to a Github organization. It was just something I wondered about.

This repo now lives in the quinn-rs organization.

[TimonPost]

There's a problem I'm struggling with. I would like to finish this project because my studies are stacking other projects on my table but at the same time, it takes quite a long time before work is reviewed. @Ralith @djc There are probably a lot of things you spend a lot of time on in daily life and that's understandable. But at the same time, I can't do this task without input and feedback from you. Therefore, if you find it possible, I would like to have more input/involvement in this documentation section so that the work can advance quicker.