|
|
|
= Google Season of Docs 2019: Ideas Page =
|
|
|
|
|
|
|
|
'''Organization name:''' The Tor Project [[BR]]
|
|
|
|
'''Organization description:''' [[BR]]
|
|
|
|
|
|
|
|
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:''' [[BR]]
|
|
|
|
|
|
|
|
- https://gitweb.torproject.org/ - official repos
|
|
|
|
- https://github.com/torproject - "unofficial" mirror
|
|
|
|
|
|
|
|
'''Website:''' www.torproject.org [[BR]]
|
|
|
|
'''Contact:''' gso@torproject.org[[BR]]
|
|
|
|
'''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 [[BR]]
|
|
|
|
'''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:
|
|
|
|
|
|
|
|
- For tor-core
|
|
|
|
- https://tor-core.readthedocs.io/
|
|
|
|
- https://trac.torproject.org/projects/tor/wiki/org/teams/NetworkTeam#Tipsonfindingyourwayaroundourcode
|
|
|
|
|
|
|
|
And a number of tickets that deal with this theme:
|
|
|
|
|
|
|
|
- https://trac.torproject.org/projects/tor/ticket/29200
|
|
|
|
|
|
|
|
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 [[BR]]
|
|
|
|
'''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 [https://2019.www.torproject.org/docs/tor-manual.html.en 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[[BR]]
|
|
|
|
'''Project Length:''' regular
|
|
|
|
|
|
|
|
=== Description ===
|
|
|
|
|
|
|
|
The [https://2019.www.torproject.org/projects/torbrowser/design/ 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 [https://2019.www.torproject.org/projects/torbrowser/design/#identifier-linkability 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 [[BR]]
|
|
|
|
'''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 [[BR]]
|
|
|
|
'''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 [https://gitweb.torproject.org/torspec.git 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[[BR]]
|
|
|
|
'''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 [https://trac.torproject.org/projects/tor/ticket/24132 here]
|
|
|
|
|
|
|
|
For Tor itself, see [https://gitweb.torproject.org/tor.git/tree/doc/HACKING doc/HACKING] in our [https://gitweb.torproject.org/tor.git/tree/ current codebase] and [https://gitweb.torproject.org/user/nickm/torguts.git/ tor guts repository].
|
|
|
|
|
|
|
|
== Project 7: Tor Browser HACKING document restructuring ==
|
|
|
|
|
|
|
|
'''Mentors:''' GeKo, pili[[BR]]
|
|
|
|
'''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 [https://trac.torproject.org/projects/tor/wiki/doc/TorBrowser/Hacking here]
|
|
|
|
The related ticket can be found [https://trac.torproject.org/projects/tor/ticket/26918 here]
|
|
|
|
|
|
|
|
== Project 7a: Update Tor Browser Hacking doc for Android ==
|
|
|
|
|
|
|
|
'''Mentors:''' GeKo, pili[[BR]]
|
|
|
|
'''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 [https://trac.torproject.org/projects/tor/wiki/doc/TorBrowser/Hacking#BuildingOrfox here]
|
|
|
|
The related ticket can be found [https://trac.torproject.org/projects/tor/ticket/30433 here]
|
|
|
|
|
|
|
|
{{{#!comment
|
|
|
|
== OONI ideas ==
|
|
|
|
|
|
|
|
=== User manuals for OONI Probe mobile apps (Android, F-Droid, iOS) ===
|
|
|
|
|
|
|
|
=== Upcoming OONI Probe desktop apps (Windows, macOS, Linux) ===
|
|
|
|
|
|
|
|
(to be launched by 30th September 2019)
|
|
|
|
|
|
|
|
=== User manual for the new OONI Explorer ===
|
|
|
|
|
|
|
|
(to be launched in May 2019)
|
|
|
|
|
|
|
|
|
|
|
|
= General notes (WIP) =
|
|
|
|
|
|
|
|
I have moved this to a comment since this will be the public page that technical writers will come to to see the proposed projects -pili
|
|
|
|
|
|
|
|
Most of the projects above are too big for one person and three months. Instead of saying "do xyz" it would be better to say "help with xyz" or "make progress on XYZ." -nickm
|
|
|
|
[I agree. I changed information from the projects that I'm voluntering myself to mentor. --gaba]
|
|
|
|
|
|
|
|
We should also note a bunch of useful subprojects here, and try to design subprojects in such a way that they are useful on their own, so that we aren't left with a half of a rewrite. -nickm
|
|
|
|
[Yes. We are expecting for technical writers to submit proposals for what to work on. This ideas here are only suggestions. We can work with them on scope of their projects to be sure that we have time to wrap up what they are doing and that it can be used. Thanks. --gaba]
|
|
|
|
|
|
|
|
We need to have 2 mentors per project. I have added back up mentors to the projects which only had one based on who I thought would be involved. Please update if my understanding is incorrect.-pili
|
|
|
|
}}} |
|
|
|
\ No newline at end of file |
