Open in app

Sign in

Write

Sign in

Project Report for Season of Docs 2019

Swati Thacker
5 min readFeb 27, 2020

--

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.

Work Done

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:

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.

Challenges

  • 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.

Learnings

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.
Gsod
Tor
Technical Writing
Open Source

--

--

Swati Thacker
Swati Thacker

Written by Swati Thacker

13 Followers
7 Following

Tech Writer || Traveller || Reader || Technology Enthusiast

No responses yet

Help

Status

About

Careers

Press

Blog

Privacy

Terms

Text to speech

Teams