Project Report for Season of Docs 2019

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

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

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

  • The Documentation Style guide is currently under review. I will continue to work with the Tor network team to finalize this style guide.

Challenges

  • 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

  • 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

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

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

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store