wiki:doc/GoogleSeasonOfDocs2019

Google Season of Docs 2019: Ideas Page

Organization name: The Tor Project
Organization description:

We are the Tor Project, a 501(c)3 US nonprofit. We advance human rights and defend your privacy online through free software and open networks.

The Tor Project is a free-software non-profit project to build an anonymity toolkit used by individuals, companies, governments, and law enforcement around the world. The Tor network has grown since its start in 2002 to several million active users pushing over 60 Gbps of traffic. The Tor Project has a staff of 45 developers, researchers, and advocates, plus several dozen volunteers who help out on a daily basis.

Git repos:

Website: www.torproject.org
Contact: gso@…
Organisation Administrators:

  • pili
  • arma

Mentors:

  • pili
  • arma
  • nickm
  • gaba
  • catalyst
  • GeKo

Blog post: https://blog.torproject.org/tor-google-season-docs-2019

Project 1: Launching docs.torproject.org

Mentors: pili, arma
Project Length: long-running

Description

The Tor Project is currently in the process of reorganising and re-designing the existing/old website (https://2019.www.torproject.org/) into a number of portals (https://trac.torproject.org/projects/tor/ticket/21222) to make it easier for different audiences to find the information that is most relevant to them. The main website: https://www.torproject.org has recently undergone this process (https://blog.torproject.org/meet-new-torprojectorg) with a focus on making it easier for new users to understand what Tor can do for them.

However, there are still many other audiences that we need to cater for and lots of documentation spread out over different locations that we need to bring together into cohesive portals. In order to help volunteer developers to understand, contribute to and potentially help us audit the code we want to make our documentation more accessible and better organised within a single location, a brand new portal: docs.torproject.org

The existing documentation page is not very user friendly and currently consists of a long page of links to many different types of information about tor. Furthermore, some of these links are not really relevant to the core tor product and would need to be re-located to dedicated portals.

We would like technical writers to submit proposals for the best way to consolidate and organise all these documents. We're open to ideas on the best way to do this, from choosing the best platform to be used to host this new documentation site, to defining the information architecture, to helping us find a good home for all of the documentation we currently have. Bonus points for choosing a solution which is easy to localise using our existing workflows or suggesting improved localisation workflows.

We want to make it super easy for volunteers with different levels of technical skills to jump in and get started with their contributions and we think a technical writer would be invaluable in helping us to do so.

Related Materials

The existing documentation page currently lives here: https://2019.www.torproject.org/docs/documentation.html.en

We also have a number of docs currently hosted on many different places:

And a number of tickets that deal with this theme:

There is also this great blog post from a volunteer that explains some of the challenges newcomers face when trying to contribute to tor: https://www.kevinsimper.dk/posts/how-to-contribute-to-the-tor-project

Project 2: Rewrite the Tor manual page

Mentors: Gaba, catalyst
Project Length:regular

Description

For this project we would like the help of a technical writer to help us re-write and improve the information architecture of the existing Tor manual page. The current tor manual page consists of a long listing of various options for the tor program including:

  • command line options
  • configuration file format and options
  • client options
  • server options
  • directory server options
  • as well as a long list of other types of options that can be configured

This list is so long that it is hard to navigate to the relevant sections and information as well as making it difficult to simply browse the different options.

We would like a technical writer to help us re-write this so that it becomes a useful reference, with a consistent style. We would also ideally like to re-order the content so that it makes more sense for users as well as summarising important options at the top and providing easy navigation between options.

Other than the suggested improvements, what would you do to make this manual easier to understand? We welcome your proposals to help us share this information more effectively.

Related Materials

You can find the existing Tor Manual here: https://2019.www.torproject.org/docs/tor-manual.html.en. Its source is "doc/tor.1.txt" in the Tor source repository.

Project 3: Updating the Tor browser design doc

Mentors: GeKo, pili
Project Length: regular

Description

The Tor Browser design document is a document that describes the adversary model, design requirements, and implementation of the Tor Browser. Unfortunately, the latest version of this document is currently outdated as it refers to Tor Browser version 7.0 and we'll be at Tor Browser version 8.5 by the end of April 2019. We would like the help of a technical writer to bring this document up to date and further, to encompass Tor Browser version 9.0 which we will start working on once 8.5 is released.

We would appreciate help with both the content and information architecture of this document. This is a critical piece of information for users and should include detailed and thorough descriptions of the different Tor Browser features, how they are implemented and why. This allows are users to take informed decisions when using Tor Browser to meet their privacy needs. In particular, one important feature which we would like to describe well in this document is First Party Isolation (FPI.) This is currently mentioned here but needs to be highlighted as an important feature and explained further.

We welcome any further suggestions from technical writers regarding the design and content of this document.

Related Materials

The current Tor Browser design doc for 7.0 can be found here: https://2019.www.torproject.org/projects/torbrowser/design/

Project 4: Help us write architecture documentation for Tor

Mentors: Gaba, nickm
Project Length: can be both short or long running depending on the scope chosen by the technical writer and any proposals received.

Description

This is a really exciting project that will help us to share Tor's architecture with a wider audience. We currently have some existing documentation, but it is incomplete and outdated.

We would welcome the help of a technical writer to help us to find holes in this documentation and make space to improve it. We would like proposals for the best ways to share this information, whether they be by including more visual elements such as diagrams, changing the information architecture and finding other more effective ways to share this information.

We want to be as transparent as we can be with our users about how Tor works. Sharing Tor's architecture will help us some way in achieving this and hopefully increase confidence in its use as well as allowing others to suggest improvements and optimisations.

Related Materials

See https://people.torproject.org/~nickm/tor-auto/internal/ for current (outdated and incomplete) documentation.

Project 5: Rewrite the Tor specifications

Mentors: Gaba, arma
Project Length: can be both short or long running depending on the scope chosen by the technical writer and any proposals received.

Description

The existing Tor specifications consist of a number of .txt files outlining different aspects of the Tor design. These files start life out as proposals, also contained in the same git repo under the proposals folder, which are discussed and refined by the team before they make it into fully fledged specifications and are moved out to the git repo root.

It would be very helpful to find a way to re-write the existing Tor specifications so we can all use them as useful references, in a consistent style and in a sensible order. It could involve writing a summary document to help people navigate the different specifications.

Further to our ideas above, what ideas do you have for displaying these without changing the underlying git repo structure? What would you do if you had to design this process from scratch? How would you change the information architecture? What would the process for submitting proposals look like and how would these make it into a final spec? We welcome proposals to answer these questions as well as any improvements that we may not have yet considered.

Related Materials

You can find the existing Tor specifications here: https://gitweb.torproject.org/torspec.git

Project 6: Rewrite the Tor developer documentation

Mentors: Gaba, catalyst
Project Length: can be both short or long running depending on the scope chosen by the technical writer and any proposals received.

Description

As a relatively small non-profit, we welcome contributions from volunteer developers to help us improve the Tor code base. However, it can sometimes be hard for new developers to know how and where to get started. We do have a number of guides to help newcomers get started contributing to our different open source projects as well as a brand new dedicated portal in the works: dev.torproject.org; to introduce developers to the work we do and how they can get involved.

Given the above, the Tor community would benefit on having documentation covering:

  • introductions for new developers
  • summary for existing developers taking on new roles
  • documentation on code structure, code standards and how we mantain and release Tor.

Related Materials

The structure for this work is outlined here

For Tor itself, see doc/HACKING in our current codebase and tor guts repository.

Project 7: Tor Browser HACKING document restructuring

Mentors: GeKo, pili
Project Length: regular

Description

The Tor Browser Hacking document is a guide for developers that want to get started on Tor Browser development.

Over the years, this document has grown organically, however, as new things get added, the document slowly starts losing shape and becoming harder to navigate for new developers wanting to get involved. We would welcome the expertise of a technical writer to help us restructure this document so that it continues being a useful resource for new contributors.

Some of our ideas include moving related applications, such as Orbot and Orfox to different (sub)-pages as well as moving the debugging guides to their own pages. We are open to all and any ideas on how we can make this document easier for people to digest, as well as keeping it easy to maintain afterwards.

Related Materials

This document can be currently found here The related ticket can be found here

Project 7a: Update Tor Browser Hacking doc for Android

Mentors: GeKo, pili
Project Length: regular

Description

This project could be part of Project 7 above and involves updating the Tor Browser Hacking doc for Android.

Related Materials

This document can be currently found here The related ticket can be found here

Last modified 6 months ago Last modified on May 8, 2019, 9:58:59 AM