Drop the 'unreliable' label from UDP. Delivery is not guaranteed, but delivery reliability largely depends on network context. Unreliable makes it sound more negative and error-prone than it is. We use UDP because and with the understanding that in most cases it is quite reliable, or reliable enough, rather than simply being unreliable. The point is that we use it for low-latency. Everything else is technical reasoning.
Prefer short statement sentences over long comma sentences.
'an TLSv1 encrypted connection' -> 'a TLSv1 encrypted connection'
Format message type name as inline code to indicate it being a "type" name.
Drop the 'unreliable' label from UDP. Delivery is not guaranteed, but delivery reliability largely depends on network context. Unreliable makes it sound more negative and error-prone than it is. We use UDP because and with the understanding that in most cases it is quite reliable, or reliable enough, rather than simply being unreliable. The point is that we use it for low-latency. Everything else is technical reasoning.
Prefer short statement sentences over long comma sentences.
'an TLSv1 encrypted connection' -> 'a TLSv1 encrypted connection'
Format message type name as inline code to indicate it being a "type" name.
This is done as a separate commit to retain Git change file history association. (Git does not store renames. It assumes renames according to content similarity.)
The cross-document reference apparently worked on readthedocs (our previous docs), but does not work on GitHub.
The cross-document figure reference is replaced with a file reference.
In a folder, GitHub shows a README by default, below the file list.
Combining the index.rst and introduction.rst, with text fixups, will serve as an appropriate landing page/doc.
Dropping the resources for Sphinx documentation generation drops support for generating this documentation into various formats (see make file; html, epub, and other less useful ones).
This network protocol documentation is the odd one out compared to our other documentation. The only one with this system.
Diverse tech has a maintenance cost, and the previous distance to our code made more likely to be missed for updates and discovery.
Handling only the network protocol documentation in this way feels disconnected/diverging.
Although readers may use the docs to implement clients and servers against only the docs, the question is whether the technology and maintenance additions are worth it.
Having simple structured text documentation files should serve us well enough.
It does for other developer documentation / documentation for developers.
