Tor Project

This page contains the details of a technical writing project accepted for Google Season of Docs.

Project summary

Open source organization:

Tor Project

Technical writer:

Swati Thacker

Project name:

Rewrite the Tor manual page

Project length:

Long running (5 months)

Project description

After a discussion with the TOR mentors to understand what their expectations from this project are, I propose the following ideas to establish a consistent structure and format for the TOR Manual page (https://2019.www.torproject.org/docs/tor-manual.html.en) in order to turn it into a useful, quick reference for users. This project will complete in 3 months and the following ideas are broken down by month.

Month 1:

Create a table of contents for this page. The TOC will include an overview topic, and the headings of all the 9 categories of configuration options. By the end of this month, the users will be able to navigate to the different configuration categories on fingertips. The TOC will look like this:

• Overview – Add information about where TOR maintains the configuration for these different option categories, if they are all at once place, the name and default location of the configuration file, the rules to use the command options, and how can users modify these options. (We can include information from the introductory text under THE CONFIGURATION FILE FORMAT topic).
• General Options
• Client Options
• Server Options
• Directory Server Options
• Testing Network Options
• Denial of Service Mitigation Options
• Directory Authority Server Options
• Hidden Service Options
• Non-Persistent Options

Note: Currently, the TOR Manual also lists a set of command-line options. For the sake of consistency and to keep the focus of this manual on configurations options, I think that the command-line options can be moved out of this page and can be linked to this page as a reference.

Month 2:

The purpose of the manual page must be to quickly answer questions about what each option does and how. Currently, the options are not documented in a structured format and information about each option is presented in paragraphs that makes it hard to find information at a glance. All the existing information about options needs to be reorganized using a template. By the end of this month, we will have a consistent format for documenting existing options and any new option in future. Additionally, this format will make it easy for the TOR manual to be used as ‘man’ pages in future.

• Firstly, add a brief description about each option category, such as, the Server Options, Client Options, and so on. The descriptions will help users know what options to expect under each category.
• Create a template to define a consistent format for documenting each option. I propose the following sections/subsections to be included in the template.
• Name: The name of the option that is being documented. Example: BandwidthBurst
• Synopsis: The summary of what the command-line syntax of the option looks like. Example: BandwidthBurst N bytes
• Description: Describe what the configuration option does, what the default value is. Example: Use this option to limit the maximum token bucket size, also known as busrt, to the given number of bytes in each direction. This option defaults to 1 Gbyte.
• Option value: List and describe the values that the option allows. Describe in detail what each value does and how should the user enter the values.

Month 3:

Currently, there are 9 groups/categories of configuration options. To enhance searchability and as a quick reference, create an index page that lists configuration options sorted alphabetically within each of the 9 categories. These categories can, then, be ordered in the priority of their usage, the most commonly used categories of options being on top.

At the end of 3 months, we can produce a refurbished TOR Manual that can be used as a quick reference by users to modify configuration settings in TOR.