Develop a short overview and walk-through of using Tor for new users

added component::user experience/tor support owner::runa priority::medium resolution::fixed status::closed type::task labels

Sounds great! We should be sure to consider folding the "frequently asked questions" section into our online faq as well.

Andrew suggested that we use Markdown when writing the document. Markdown can easily be converted to latex, pdf, or html. Converting it to po (so that we can feed it to Transifex) isn't too difficult either.

Replying to runa:

Andrew suggested that I work with Jeremy to make this 4-5 page brochure/manual look pretty and be able to turn into a pdf for shipping around the Internets.

The brochure/manual can be found here: https://media.torproject.org/image/tor-circumvention-brochure-001c.pdf

See https://gitweb.torproject.org/user/runa/tor-manual.git for progress.

We should look into shipping this manual in a format other than PDF. Robert suggested plain text (without images) or HTML (either without images or with images specified as 'data:' URLs).

Here's a shameless copy&paste from IRC;

"XHTML with embedded SVG might work, too, but I'm pretty sure you can't make a usefully small SVG from the image. HTML is potentially human-readable without a browser. PDF can contain scary JavaScript, and there's no way for users to find out whether a PDF is safe to view. Both formats can 'phone home', and are probably capable of sending files from the user's filesystem to the Internet, but with an HTML file, a sufficiently paranoid user can view it as text safely."

" A data: URL is a URL which contains the data of the resource it names. There's a spec on the Mozilla developer website. Also, the user's webmail service can display an HTML file more nicely than it can display a PDF file. You can probably find examples of data: URLs in an exported Firefox bookmarks file (export to HTML)."

Here's a sample of part of a data: URL from my exported bookmarks file: data:image/png;base64,iVBORw0KGgoAAAANSUh

But if we create a (new) SVG image and embed that instead, we might also get to have the text in the image translated.

Replying to runa:

"XHTML with embedded SVG might work, too, but I'm pretty sure you can't make a usefully small SVG from the image. HTML is potentially human-readable without a browser. PDF can contain scary JavaScript, and there's no way for users to find out whether a PDF is safe to view. Both formats can 'phone home', and are probably capable of sending files from the user's filesystem to the Internet, but with an HTML file, a sufficiently paranoid user can view it as text safely."

We can easily create HTML instead of PDF. I'm sure we can do XHTML as well. I have asked Jeremy if he can do SVG instead of PNG for the image we use.

" A data: URL is a URL which contains the data of the resource it names. There's a spec on the Mozilla developer website. Also, the user's webmail service can display an HTML file more nicely than it can display a PDF file. You can probably find examples of data: URLs in an exported Firefox bookmarks file (export to HTML)."

What's the benefit of using data: URL instead? I tried it with the current image, and it works just fine (if you ignore the fact that the base64 representation is a ton of lines).

I prefer to see us ship something to users soon, so we can get feedback and adjust accordingly. We should ship the minimum text necessary to get someone safely using Tor. Perhaps we can ship the FAQ and other stuff as additional text files, or direct links to our site.

Replying to phobos:

I prefer to see us ship something to users soon, so we can get feedback and adjust accordingly. We should ship the minimum text necessary to get someone safely using Tor. Perhaps we can ship the FAQ and other stuff as additional text files, or direct links to our site.

I agree. Ideally, I want us to have English and Farsi available before the 17th (when we're expecting another round of mass emails) and have GetTor automatically ship them out. One option is to just ship HTML to begin with, since that's a safer/better/nicer option than PDF.

If you want to comment on the contents of this manual, please do so today. I'd hate to get the translated version ready, ship it all out and then deal with "we should add xyz, or you should write abc in a different way". The idea is that, once it's ready, it's ready and we don't change it unless it's necessary to do so.

phobos; kaner wonders if we can put the manual in /dist/ so that GetTor can rsync and send it out with every package. Thoughts?

Trac:
Cc: N/A to phobos, kaner

Replying to runa:

phobos; kaner wonders if we can put the manual in /dist/ so that GetTor can rsync and send it out with every package. Thoughts?

My general thoughts are that /dist needs to go away and be replaced with archive.torproject.org. Can't gettor just curl the file from the website?

Replying to runa:

If you want to comment on the contents of this manual, please do so today. I'd hate to get the translated version ready, ship it all out and then deal with "we should add xyz, or you should write abc in a different way". The idea is that, once it's ready, it's ready and we don't change it unless it's necessary to do so.

Patch sent.

Replying to phobos:

Patch sent.

Does anybody else get to see it? :)

Replying to arma:

Replying to phobos:

Patch sent.

Does anybody else get to see it? :)

When she commits it. I don't have commit access to her repo.

Trac:
0001-use-consistent-headers-at-times-replace-some-of-the-.patch

Replying to runa:

If you want to comment on the contents of this manual, please do so today.

Thoughts, from higher priority to lower priority.

A) "If Tor still doesn't work, it's likely that your Internet Service Provider (ISP) is blocking Tor." I think we should try to clarify the countries in which this is true. To my knowledge the country where it is true is China; it is not true outside of China -- and in China, the bridges you get from bridgedb probably aren't going to work for you anyway.

https://www.torproject.org/docs/faq#DoesntWork needs a rewrite now that TBB is our favored install, but it has some good suggestions for what to do if Tor still doesn't work. Smart ones include "look at your Vidalia message log window" and "are you running a security or antivirus tool that is breaking Tor's ability to use the network".

I think we probably want to include bridges and the open proxy config suggestions as a separate section ("be prepared for when your government tries to block Tor"), and focus on giving people debugging tips if their Tor doesn't work, rather than telling them to use a bridge.

In the bridge section, we should also tell them to expect to have to fetch a new set of bridges every few days since the ones they get will go down (we tell them to set several, but we should explicitly tell them they'll want to build a habit of fetching new ones).

B) Some points are not currently accurate, e.g. 1) you say that gettor works with macosx, yet currently it doesn't because the bundle is too big for all common mailservers. 2) "All you need to do is join the HTML5 trial" is not true right now either, since Torbutton somehow prevents the join cookie from sticking.

If we're planning to roll this out to people asap, should we try to make it accurate for now, and then plan to change it later once we make things work better?

C) Littler things:

In the "How Tor works" section, you say 'server' in many cases where we've chosen in all the other docs to say 'relay'. We originally opted away from server because it gives people an image of a huge centralized IBM machine maintained by The Tor Project rather than a computer somewhere.

"It is technically possible to use Tor with other browsers, but by doing so you may open yourself up to potential attacks." doesn't need the 'may'.

D) The section on checking the signature doesn't teach the user anything about what GPG actually does. We might as well just ship them SHA-1 hashes of the download files. We should plan to clean up the verifying-signatures page to explain trust chains, and extract key points from it into an updated version of this text. That process shouldn't block getting this document out the door though.

Replying to phobos:

Replying to runa:

If you want to comment on the contents of this manual, please do so today. I'd hate to get the translated version ready, ship it all out and then deal with "we should add xyz, or you should write abc in a different way". The idea is that, once it's ready, it's ready and we don't change it unless it's necessary to do so.

Patch sent.

I've applied parts of the patch. See my comment below for your changes to the first section.

+The image above illustrates a user browsing to the Torproject.org website
+using Tor. The green monitors represent relays in the Tor network,
+while the three locks represent the layers of encryption between the
+user and each relay.

How do you suggest that we illustrate the Tor Project website? I guess one option would be to drop the Twitter icon and put a URL there instead. I wanted to use an image that "everyone" knows, and not use any text in the image at all. So I figured Twitter would be a good fit.

Also, I know that we normally use the world "relay" instead of "server". However, a word like "relay" does not make much sense to non-tech users, and it can be difficult to translate. I figured "server" would be better in a short manual for new Tor users.

Replying to arma:

Replying to runa:

If you want to comment on the contents of this manual, please do so today.

Thoughts, from higher priority to lower priority.

A) "If Tor still doesn't work, it's likely that your Internet Service Provider (ISP) is blocking Tor." I think we should try to clarify the countries in which this is true. To my knowledge the country where it is true is China; it is not true outside of China -- and in China, the bridges you get from bridgedb probably aren't going to work for you anyway.

Why mention the country if we're talking about one single country where bridges probably aren't going to work anyway? Also, I would rather not have to update the document every time we learn about a country where you need to use a bridge.

https://www.torproject.org/docs/faq#DoesntWork needs a rewrite now that TBB is our favored install, but it has some good suggestions for what to do if Tor still doesn't work. Smart ones include "look at your Vidalia message log window" and "are you running a security or antivirus tool that is breaking Tor's ability to use the network".

I've created #4219 (moved) for the website FAQ, and I have updated the manual with some tips for debugging Tor. I have also mentioned emailing community-support with relevant parts of the log so that we can help debug.

I think we probably want to include bridges and the open proxy config suggestions as a separate section ("be prepared for when your government tries to block Tor"), and focus on giving people debugging tips if their Tor doesn't work, rather than telling them to use a bridge.

Fixed.

In the bridge section, we should also tell them to expect to have to fetch a new set of bridges every few days since the ones they get will go down (we tell them to set several, but we should explicitly tell them they'll want to build a habit of fetching new ones).

Fixed.

B) Some points are not currently accurate, e.g. 1) you say that gettor works with macosx, yet currently it doesn't because the bundle is too big for all common mailservers. 2) "All you need to do is join the HTML5 trial" is not true right now either, since Torbutton somehow prevents the join cookie from sticking.

For (1): I moved the "Cannot get the package from GetTor" section up to the section that talks about how to get packages Tor via email.

For (2): Ah, I guess that's #3347 (moved). What should we tell the users? Use the HTML5 trial, but you will need to rejoin every time?

If we're planning to roll this out to people asap, should we try to make it accurate for now, and then plan to change it later once we make things work better?

I'm going to "accurate for now, we can always update it later".

C) Littler things:

In the "How Tor works" section, you say 'server' in many cases where we've chosen in all the other docs to say 'relay'. We originally opted away from server because it gives people an image of a huge centralized IBM machine maintained by The Tor Project rather than a computer somewhere.

I know that we normally use the world "relay" instead of "server". However, a word like "relay" does not make much sense to non-tech users, and it can be difficult to translate. I figured "server" would be easier to understand/translate in a short manual for new Tor users.

"It is technically possible to use Tor with other browsers, but by doing so you may open yourself up to potential attacks." doesn't need the 'may'.

Fixed.

D) The section on checking the signature doesn't teach the user anything about what GPG actually does. We might as well just ship them SHA-1 hashes of the download files. We should plan to clean up the verifying-signatures page to explain trust chains, and extract key points from it into an updated version of this text. That process shouldn't block getting this document out the door though.

It doesn't give users a long explanation, but it does say that checking the signature is a way of verifying that you have the right version of Tor and that it hasn't been tampered with. I agree that we should update the verifying-signatures page, and I've created #4218 (moved) for this task. Once that's done, I'll update the user manual with key points.

I'll wait for you and Andrew to comment before I ask people to start translating. I want to be able to ship this manual to everyone who requests a package from the 17th, and I also want us to have a Farsi translation by then.

We can still discuss and edit the manual after that, but I'd rather not make too many changes to the document once people have started to translate.

Replying to runa:

Also, I know that we normally use the world "relay" instead of "server". However, a word like "relay" does not make much sense to non-tech users, and it can be difficult to translate. I figured "server" would be better in a short manual for new Tor users.

There are two risks here. First is that the users come in with some notion of what a server is that contradicts the concept we're trying to communicate to them. Second is that the users then go on to read more Tor documents, and they wonder why the terms change.

The 'difficult to translate' part reminds me of another suggestion we were pondering a while ago: when we have five Arabic translators, they each need to figure out what word to use for each of the Tor terms. We should help translators for each language to come up with and document a common set of corresponding terms for their language.

Develop a short overview and walk-through of using Tor for new users

Child items ...

Activity