Skip to content

Cleanups and improvements on Tor specifications

About the project

Participants

  • Nick Mathewson
  • etc

Summary

We recently migrated our protocol specifications to mdbook, in preparation for a larger round of revisions and improvements.

This week, we'll be working on the follow-ups from that transition, and other general improvements on the specifications.

Project A: Simple mdbook-related followups

Our conversion process was largely a mechanical one, and there is substantial opportunity for improving its results. This might take the form of:

  • Looking for instances of ``` blocks that can instead be formatted better as tables, indented text, or some other kind of information.

  • Looking for occurrences of "See section X.Y.Z above" or similar text that can be turned into links.

  • Looking over our existing links, and making sure that they are well considred.

  • Looking for misformatted text in the output, and correcting the markdown that generated it.

  • Making the resulting documentation better fit our themes and style guidelines.

This will not be a purely mechanical process. You will need to make sure that you understand what you are reading well enough to be sure that you aren't changing its meaning, that your links really are going to the intended text, and so on.

Project B: Revisions for clarity and consistency

This year marks the twentieth anniversary of our first attempt at a protocol specification. Over the years, as our protocol grew,and as our terminology evolved, we have revised and extended the specs bit by bit, but seldom had a chance to consider their readability as a whole.

With this project, we will be looking for was to improve our specifications as a whole, by fixing issues like:

  • Inconsistent or outdated terminology
  • Missing explanations
  • Material without sensible motivation
  • Lack of distinction between specification and analysis
  • Illogical ordering and division of chapters
  • Obscure writing
  • Lack of overall introductions
  • Historical notations of limited relevance
  • Outdated notes about years-unsupported versions of Tor, or plans from the distant past.

Again, this cannot be a mechanical process: you don't need to be an expert in the Tor protocols to work on this, but also you can't just search and replace old terms for new ones, or rewrite text without taking time to understand what it means.

Skills

Before you begin, you should make sure that you can use git, edit markdown, and make merge requests on https://gitlab.torproject.org/.

It would also be a good idea to make sure that you can build the HTML-rendered spec website locally. There is a script to do that in the specification repository; you will need to make sure that you have Python and mdbook installed.

Finally, you should be comfortable reading and writing specification documents of this type, and you should have some idea of how Tor works.

Links

Edited by Nick Mathewson