Google Season of Docs 2019: Help Tor Improve Our Documentation

by pili | April 23, 2019

There are a few elements that are critical for the sustainability of an open source project. One of them is good documentation.

Although often neglected, documentation can be crucial for open source projects to provide meaningful guides on how to start contributing and guides on the architecture of the technology being developed.

These resources help not only newcomers and contributors to understand the technological aspects of a project but can also expose both decision making and work processes, outlining the best way to contribute.

This year Google has launched Season of Docs, similar to Summer of Code. Season of Docs brings open source and technical writer communities together. The aim is to foster collaboration and give technical writers the “experience in contributing to open source projects, and to give open source projects an opportunity to engage the technical writing community.”

The program runs for approximately 3 months from September to November 2019 and there is additionally the option of a "long-running project" which goes on for approximately 5 months, from September 2019 to February 2020.

We are pleased to announce that we have been accepted as a mentoring organization for Google’s Season of Docs 2019.

We’re a small nonprofit organization that develops free and open source software used by millions around the world, and our community of contributors and users would greatly benefit from improved documentation.

Through Season of Docs, we want to collaborate with technical writers who can help us with these projects:

  • Tor Manual: We would like to re-think the information architecture of the Tor manual.  ​
  • Tor Specifications: We have several documents outlining how different elements in Tor work. We would like to rewrite them so they can be useful references.
  • Tor Browser Design Doc: We would like to re-think the information architecture of this document and bring it up to date for the latest Tor Browser versions.
  • Developer documentation: We would like to consolidate and rewrite the developer documentation for new contributions and volunteers that are taking new roles in the community.
  • Tor Documentation: We would like to reorganize and rewrite part of the existing documentation.

You can read other possible documentation projects at Tor in our wiki, and we are open to other ideas, too. We would love to read your own proposals about how we could improve any of our documentation.

Applications for Google Season of Docs open on May 29, 2019 at 18:00 UTC. We welcome you to discuss your project with us before applying. You can email us with your ideas or questions at

We look forward to working with you.


Please note that the comment area below has been archived.

May 02, 2019


"We", "we", "we would like to", "we want to" + [ambiguous action]. Sounds like you already have strong editorial feelings for what you want. Comments from the (user) community sound satisfied for the most part with the language of the documentation, old and new, except when they can't find it. What could a writing volunteer contribute but copy and paste while filling in outline drafts from micro-managed subjective orders? Was this initiative brought on by comments from users? Because the post cites none. Or is it something to do to look busy as a follow up from grant requests?

When asked we put in a lot of suggestions. Where are they now? Is T.O.R. yours or ours? Aren't relay and exit operators (from our pockets) T.O.R. and therefore the community and us and you are one? you say is this year's site but half the links don't go to that one. They go to the usual one.
You've disappeared up your own artifice.

May 02, 2019


[...] all of the people who have been involved in Tor are united by a common belief: internet users should have private access to an uncensored web.

Google is probably the biggest non-government enemy of "private access to an uncensored web".
I cannot fathom how white-washing them in this way can possibly advance this cause.

May 03, 2019


I'm watching my privacy melt away before my very eyes. I can't block script on this new version of Tor and am getting Google trackers and am clearly being finger printed by google; also, it would appear that I'm being tracked by the Google Geo-location. There's not a simple way to stop this. Indeed, it feels like Tor has been bought out by the Google. :(

May 03, 2019


This is a worthy effort and I hope that it results in documentation which helps newcomers quickly learn what they need to know right now to start using Tor Browser, while also making it easy for more experienced users to find up to date information on topics such as encryption used in Tor circuits or links to key papers on theoretical attacks on onions, plus information about real world attacks in the wild.

Because I am a user but neither a coder nor a tech writer I consider myself well qualified :-) to offer some general advice about writing "tech docs for the ordinary citizen".

One basic approach might be to write a core page for newcomers with links to other pages with more specialized/detailed information, or to pages which discuss difficult topics like Tor Project's somewhat troubling (especially for newcomers outside the US) historical origins, criminalization of privacy research (c.f. Ola Bini), or the community response to FBI's "Going Dark" hysteria. I suspect no-one at Tor will be eager to pen a thoughtful admission that Yasha Levine makes some good points in his book Surveillance Valley, but I think acknowledging past mis-steps (such as hiring a former USIC coder to work on sensitive app code) is the best way to convince wary potential users that TP has seriously reformed its character from "US soft power coders" to "international human rights coders".

I was very impressed when I first read the Tails documentation because that was the first site I'd seen which followed the rule of putting the essential stuff first and then adding links to comprehensible explanations of how to use various software bundled with Tails. Infinitely superior to off-putting injunctions to RTFM (meaning the Tor Design Document, which is not really written for users but for coders, and is in any case seriously outdated).

Here and there the writers can possibly insert encouragement to intermediate level users: when we say understanding privacy tech involves surmounting a "steep learning curve", we mean that initially a newcomer might find almost everything confusing or counterintuitive, but if they keep using Tor and trying to learn more about how the magic happens, at some point they will find more and more is rapidly making more and more sense to them.

Because things change so quickly, every page should begin with "last reviewed April 2020" etc. Because many people will come across these documentation via a search engine, and because search engines often link to outrageously outdated and even dangerous misleading information about Tor, regular review and updating should be an essential part of documentation.

Last but not least, rigorous link testing, editing, and some kind of user testing before you launch should be regarded as essential. The recent launch of the "new look" was more rocky than it should have been. I hope that just before you announce the new documents in this blog someone will test the blog post using various security slider selections (by that time there may be four not three as you know!) and if possible using slow as well as fast internet connections. Remember that some Tor users are not in regions with fast internet and we do not want to make life more difficult for them than it already is.

P.S. Please make sure Isabela knows about (and ideally responds to) a troubling opinion piece which calls for (among other things) DARPA funding of anti-GFWC software without even mentioning Tor! Or anonymity or privacy. See:
Tear down the 'Great Firewall' to win the war with China
Bradley A. Thayer and Lianchao Han
29 Apr 2019

When you read this, make sure to note the authors's affiliations:

> Bradley A. Thayer, Ph.D., is a professor of political science at the University of Texas, San Antonio. He is coauthor of “How China Sees the World: Han-Centrism and the Balance of Power in International Politics.”

UT San Antonio has close ties to NSA/TAO, which is situated on the grounds of Lackland AFB in that city. Several companies in San Antonio are essential cybermercenary companies staffed by former US military USIC cyberwarriors. Don't know about Thayer himself, but possible ties to NSA/TAO are concerning.

> Lianchao Han is vice president of Citizen Power Initiatives for China and a visiting fellow at the Hudson Institute. After the Tiananmen Square Massacre in 1989, Dr. Han was one of the founders of the Independent Federation of Chinese Students and Scholars. He worked in the U.S. Senate for 12 years, as legislative counsel and policy director for three senators.

Hudson Institute: conservative think tank founded by thermonuclear extremist Herman Kahn. Don't know about Han himself, but these ties are concerning.

Simultaneously, Pompeo appears to be trying to co-opt HRW's very important revelation of the massive dragnet surveillance/harassment system tracking Uighurs everywhere they go in China (not just in Xinjiang Province) by calling out the CN government for (apparently) incarcerating millions of heads of Uighur households in vast internment camps (called "vocation training centers", with guard towers).

I am concerned that Thayer and Han may be players is a well planned political influence campaign whose goals may include

o delegitimizing (even criminalizing) Tor

o decoupling "anti-censorship" from anonymity, privacy, and even from free speech

o making a show of ideological combat with CN (but certainly not RU!) while quietly encouraging FBI's "Going Dark" ambitions of eliminating all on-line privacy.

Also, I think Isabela may be too young to remember that the Democratic candidate for US President in 2020 who is being heavily promoted by "the establishment", Joe Biden, was one of the chief proponents of NSA's "clipper chip" and other attacks on NSA-defeating public key cryptography. He was also one of the chief architects of one of the most socially destructive laws in US history, the Crime Omnibus (mandatory sentencing, etc). And his son turns out to have invested heavily in the very surveillance app which plays a key role in the CN Uighur-tracking/harassment dragnet.

I hardly need remark that Drump agrees with CN on the "need" for cyberactions (and "kinetic" actions) targeting "troublemakers" (e.g. ACLU, left leaning journalists, community organizers, union leaders) as a "national security matter" [sic], so Pompeo's criticisms will not be taken seriously by the international community.

Further, tech reporter Sean Gallagher, who years ago was not unfriendly to reporting on the Snowden leaks, now appears to have been thoroughly co-opted by the US military/USIC cyberwarrior mythology:
Spot the not-Fed: A day at AvengerCon, the Army’s answer to hacker conferences
Army unit's effort brings hacker con culture to the home of military cyber.
Sean Gallagher
2 May 2019

In short, Tor (and the right to privacy, and the right to freedom from cyberassault from the likes of NSA/TAO) has few friends in the US executive, legislature, judiciary, or media.

It follows that Tor Project must redouble its efforts to move to a user funded structure, and to relocate its base of operations to a safer country. So not RU, not CN, not VE, probably not BR or MX, but maybe CH or SE or IS or even Chile? Or those seem too far, what about CA? Not really safe but safer than the US, probably.

Your P.S. is 150% longer than your post. Brevity, please! Microblog or real-time chat sometime. Tor Project posts on Mastodon and operates IRC channels. Your main post makes some good basic points, but they are as lost as needles in a haystack. Tech writing is supposed to avoid political subjectivity. It's supposed to be concise, direct, clear, simple -- in effect, dry.

May 04, 2019


Emergency alerts are a very special but very important type of documentation. Users have begged TP for years to try to develop a faster response. E.g. you are a small organization but not so small that someone cannot be designated as the person who will respond within minutes to a security crisis.

As of today (4 May 2019) (?) is saying:

> Tor Browser in Tails 3.13.1 is not safe to use without taking the manual steps listed below each time you start Tails!
> Due to a mistake in Mozilla's signing infrastructure all Firefox and Tor Browser add-ons are currently disabled, which disables important protections (the NoScript add-on) for Tails users.
> To secure your Tor Browser you must follow these steps each time you start Tails 3.13.1:
> Open the address about:config in the Tor Browser address bar
> Click the "I accept the risk!" button
> At the top of the page, search for xpinstall.signatures.required
> Set the xpinstall.signatures.required entry to false by double clicking it
> To the right of the address bar an icon with a blue S (and possibly a red question mark or other variations) should appear, and this indicates that your browser is safe again.

Is this genuine? We want to change the value from TRUE to FALSE? Disabling the requirement for signatures?

Does this affect the current version of Tor Browser offered by Tor Project as well as the version in Tails 3.13.1?

Does this affect user irrespective of their security slider setting?

Does this affect only Windows users?

Was the mistake made by Mozilla?

Is this good as bad as it sounds? Bad guys can remotely install any add-on they please by messing with the code on some popular website? Is that what the "signing infrastructure" mistake implies?

May 10, 2019


Good technical writing style guideline documents: