In 2019, Google introduced the Season of Docs program to bring technical writers and open source organizations together on the same platform. My proposal to rewrite the Tor manual was accepted and I was officially inducted into the world of open-source documentation.
Tor (The Onion Router) is an open-source software that enables users anonymity online by encrypting internet traffic and passing it through a series of nodes. The Tor network team maintains the Tor configuration options and the command-line options in the Tor manual. Given how huge this manual is, I undertook the task of reorganizing and structuring the information in this manual to enhance readability and searchability.
The Tor Manual consists of a comprehensive list of command-line and configuration options. The configuration options were broadly categorized into ten groups and each group contains many options that did not follow any logical sorting. Also, the HTML page did not have a table of contents (TOC). These made it extremely difficult to navigate through the different categories of options and find what you’re looking for. The links to internal cross-references and some external references did not use hyperlinks, which defeats the very purpose of using references.
As part of GSoD, I undertook the task of breaking down the bigger groups of configuration options into smaller logical groups and sorting them alphabetically within these groups. I also added a table of contents to the manual for easy navigation on the HTML pages. I proof-read, reworded and edited content to comply with grammar rules and tech writing standards. Additionally, I created a documentation style guide that outlines a list of guidelines and standards specific to documenting the Tor manual.
My mentors during this program were Taylor and Gaba, and they have provided phenomenal support. The entire Tor team has been very encouraging and motivating.
The new and merged Tor Manual can be found here: Tor Manual.
Summary of the Commits
Here’s a list of all my commits that have been merged into the Tor repository:
- https://github.com/torproject/tor/pull/1437: Reworded and proof-read the FILES section and back matter (SEE ALSO, BUGS, AUTHORS). This pull request was created by my mentor to split my main PR (https://github.com/torproject/tor/pull/1391) into smaller PRs for ease of review.
- https://github.com/torproject/tor/pull/1468: Reworded and edited the DESCRIPTION and COMMAND-LINE OPTIONS sections. Improved formatting. This pull request was created by my mentor to split my main PR (https://github.com/torproject/tor/pull/1391) into smaller PRs for ease of review.
- https://github.com/torproject/tor/pull/1567: Alphabetically sorted config options in the GENERAL OPTIONS category. The exceptions were marked with an //Out of order comment. This PR was revised by my mentor and merged using PR — https://github.com/torproject/tor/pull/1590.
- https://github.com/torproject/tor/pull/1632: Alphabetically sorted config options in the CLIENT OPTIONS category. The exceptions were marked with an //Out of order comment. My mentor fixed minor issues and merged this PR using a new PR — https://github.com/torproject/tor/pull/1643.
- https://github.com/torproject/tor/pull/1702: To split the manpage entries into smaller, logical categories, added three new options categories titled ‘CIRCUIT TIMEOUT OPTIONS’, ‘DORMANT MODE OPTIONS’, and ‘NODE SELECTION OPTIONS’. Added descriptions for all these categories.
- https://github.com/torproject/tor/pull/1715: Alphabetized config options in the SERVER and DIRECTORY SERVER option categories. Also, I added a new category titled STATISTICS OPTIONS to split out the statistics-related options.
- https://github.com/torproject/tor/pull/1737: Alphabetically sorted the following four option categories:
DENIAL OF SERVICE MITIGATION OPTIONS
DIRECTORY AUTHORITY SERVER OPTIONS
HIDDEN SERVICE OPTIONS
TESTING NETWORK OPTIONS
Marked all exceptions with the //Out of order comment.
- https://github.com/torproject/tor/pull/1759: Added a TOC for easy scrolling on the HTML page.
Standardized the cross-reference format.
Added hyperlinks to all cross-refs within the doc.
For further details of all of my commits, you can refer to my git repository here.
Apart from the work on the Tor manual, I have created a documentation style guide that outlines the guidelines and conventions that should be followed while making contributions to the Tor Manual. To maintain consistency of format and structure, it is essential to have a set of guidelines for all future contributions. This style guide is still under review. It may expand over time and will be hosted in the Tor repository.
The Current State of the Project
- All the above-listed pull requests that contain my work have been thoroughly reviewed and merged into the Tor repository. These updates are expected to go-live during the next release cycle, that is, Tor 0.4.3, which is due on April 15, 2020.
- The Documentation Style guide is currently under review. I will continue to work with the Tor network team to finalize this style guide.
- This manual is the single source of content for the Tor manpages as well as the HTML version. Therefore, some ideas that I had originally proposed were not possible to implement in the format used by manpages. Therefore, I had to re-scope the project around these limitations.
- To see the output of my changes on the manpages, I was required to install and build tor. This turned out to be quite challenging because it required Mac or Linux OS while I was using Windows. After several failed attempts of installing the Windows subsystem for Linux, thanks to the continuous support from my peers and mentors from the tor network team, I was able to successfully install tor and build the manpages on a borrowed Mac machine.
- Since this was my first experience with open-source documentation and my little prior experience of using git, I was unaware of the nature of commits to be submitted for reviews. I submitted my first commit comprising a lot of formatting changes and content changes together. This made it difficult for my mentors to review the changes. Therefore, my mentor had to break these changes down into multiple pull requests.
- Because of unforeseen roadblocks, I have had to switch my project from a short-term to a long-running project. Thanks to my mentors for their support that I could make up for my lost time during these extra months.
The past 5 months have been a valuable learning experience and these experiences will help me make successful future contributions to the open-source world.
- Owing to the international nature of the community, I learned to be aware of the time and cultural differences. Set alarm for meetings, especially the late-night ones!
- Embrace changes and be ready to adapt to newer opportunities in case you have to re-scope your original proposal.
- When scoping time for the project, always allow time for roadblocks, setting up the work environment, and establishing communication channels with the community.
- Be open-minded and flexible to use the tools and conventions that the community uses.
- I have become better at managing time to strike a balance between a project and a full-time job.
Future Work Plan
- The Documentation Style guide is currently under review. I will continue to work with the Tor network team to help make a final style guide.
- In my proposal, I had suggested splitting the command-line
options into their own page because the manpage is too large to
read easily. Due to time constraints and other priority release commitments, we could not work on this. I’ll continue to work with my mentors to implement this.