Stay organized with collections
Save and categorize content based on your preferences.
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
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.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Missing the information I need","missingTheInformationINeed","thumb-down"],["Too complicated / too many steps","tooComplicatedTooManySteps","thumb-down"],["Out of date","outOfDate","thumb-down"],["Samples / code issue","samplesCodeIssue","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2024-11-08 UTC."],[[["\u003cp\u003eThis project aims to rewrite the Tor manual page for improved usability and clarity.\u003c/p\u003e\n"],["\u003cp\u003eThe project will create a clear table of contents, categorize configuration options, and establish a consistent documentation template for each option.\u003c/p\u003e\n"],["\u003cp\u003eAn alphabetical index of options will be created for enhanced searchability and quick reference.\u003c/p\u003e\n"],["\u003cp\u003eThe rewritten manual will serve as a comprehensive guide for users to understand and modify Tor configuration settings.\u003c/p\u003e\n"],["\u003cp\u003eThis project spans five months and is part of Google Season of Docs, focusing on the open-source Tor Project.\u003c/p\u003e\n"]]],["The core actions of this technical writing project focus on restructuring the Tor manual page. Month one involves creating a table of contents with nine configuration categories and an overview, relocating command-line options. Month two focuses on developing a consistent documentation template with sections for option name, synopsis, description, and values. It will also include a brief description of each category of options. Month three will create an indexed, alphabetized listing of options within each category, ordered by priority of use. The end result is a user-friendly, quick-reference Tor manual.\n"],null,["# Tor Project\n\nThis page contains the details of a technical writing project accepted for\nGoogle Season of Docs.\n\nProject summary\n---------------\n\nOpen source organization:\n: Tor Project\n\nTechnical writer:\n: Swati Thacker\n\nProject name:\n: Rewrite the Tor manual page\n\nProject length:\n: Long running (5 months)\n\nProject description\n-------------------\n\nAfter 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 (\u003chttps://2019.www.torproject.org/docs/tor-manual.html.en\u003e) 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.\n\n### Month 1:\n\nCreate 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:\n\n- 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).\n- General Options\n- Client Options\n- Server Options\n- Directory Server Options\n- Testing Network Options\n- Denial of Service Mitigation Options\n- Directory Authority Server Options\n- Hidden Service Options\n- Non-Persistent Options\n\n| **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.\n\n### Month 2:\n\nThe 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.\n\n- 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.\n- Create a template to define a consistent format for documenting each option. I propose the following sections/subsections to be included in the template.\n- Name: The name of the option that is being documented. Example: BandwidthBurst\n- Synopsis: The summary of what the command-line syntax of the option looks like. Example: BandwidthBurst N bytes\n- 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.\n- 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.\n\n### Month 3:\n\nCurrently, 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.\n\nAt 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."]]
