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.

Replying to arma:

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.

Ok, I've updated the text to say relays instead of servers.

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.

This is true for any language where we have more than one translator. Transifex has a comment field associated with each English string, so it is possible for translators to talk about these things.

Replying to arma:

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.

Regarding the HTML5 YouTube trial, the document now says:

Note that the browser will not remember that you joined the trial once
you close it, so you will need to re-join the trial the next time
you run the Tor Browser Bundle.

Replying to runa:

Replying to arma:

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.

Regarding the HTML5 YouTube trial, the document now says:

{{{ Note that the browser will not remember that you joined the trial once you close it, so you will need to re-join the trial the next time you run the Tor Browser Bundle. }}}

telling people to login to youtube to get the html5 cookie is a poor answer for us.

Replying to phobos:

Replying to runa:

Replying to arma:

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.

Regarding the HTML5 YouTube trial, the document now says:

{{{ Note that the browser will not remember that you joined the trial once you close it, so you will need to re-join the trial the next time you run the Tor Browser Bundle. }}}

telling people to login to youtube to get the html5 cookie is a poor answer for us.

You don't have to login, you just need to visit the page and click a button. Telling people to enable flash in Torbutton to view videos is worse.

I decided to declare the user manual final (or "final for now"), converted the .text to .pot and added it to Transifex: https://www.transifex.net/projects/p/torproject/resource/1-tsum-pot/

Now we just need to (1) find a place for it on https://torproject.org/, and (2) make GetTor send it out to users automatically.

I thought we were including this with packages?

Should we also turn this into a release tag and keep the latest released version of it on torproject.org/docs?

Replying to phobos:

I thought we were including this with packages?

The idea is that GetTor will ship the manual to anyone who requests a package or asks for help. I was thinking we could make it available on torproject.org as well. Thoughts?

Replying to phobos:

Should we also turn this into a release tag and keep the latest released version of it on torproject.org/docs?

I don't know "release tag" means in this case, but sure, sounds great.

Replying to runa:

Replying to phobos:

I thought we were including this with packages?

The idea is that GetTor will ship the manual to anyone who requests a package or asks for help. I was thinking we could make it available on torproject.org as well. Thoughts?

If it isn't shipped with the packages, TBB at least, users have to take extra steps to get it, which means few will do so. If you get TBB from a friend, you've never visited torproject.org and won't know this exists.

Replying to runa:

Replying to phobos:

Should we also turn this into a release tag and keep the latest released version of it on torproject.org/docs?

I don't know "release tag" means in this case, but sure, sounds great.

we could move it out of your user dir on git, and do 'git tag' for releases when we agree it's in a stable state.

Replying to phobos:

Replying to runa:

Replying to phobos:

I thought we were including this with packages?

The idea is that GetTor will ship the manual to anyone who requests a package or asks for help. I was thinking we could make it available on torproject.org as well. Thoughts?

If it isn't shipped with the packages, TBB at least, users have to take extra steps to get it, which means few will do so. If you get TBB from a friend, you've never visited torproject.org and won't know this exists.

It will be shipped with the packages, but not inside the packages. The manual explains how to verify the package you downloaded, and also how to extract the package archive. Putting the manual inside the package won't make any sense.

Also, I suggest we update the text on check.torproject.org to say "Hey, if you need help, download this fancy user manual".

Replying to phobos:

Replying to runa:

Replying to phobos:

Should we also turn this into a release tag and keep the latest released version of it on torproject.org/docs?

I don't know "release tag" means in this case, but sure, sounds great.

we could move it out of your user dir on git, and do 'git tag' for releases when we agree it's in a stable state.

Sure, we can do that.

Replying to runa:

It will be shipped with the packages, but not inside the packages. The manual explains how to verify the package you downloaded, and also how to extract the package archive. Putting the manual inside the package won't make any sense.

Ok, let's step back. One point of the user manual is to help users without, or with unsafe, web access to torproject.org, to configure tor correctly, and get some basic questions answers.

Another point is to provide "tor in a nutshell with quick debugging tips" for users. This should help explain Tor to new people and maybe reduce support requests.

We need to have the tor manual included with the packages. What's included already is too confusing for most users. If it's not there by default, I imagine few will know how to get it.

Also, I suggest we update the text on check.torproject.org to say "Hey, if you need help, download this fancy user manual".

We should integrate this with the new check html. Do we do this for failures only? or as the default doc for /docs?

Replying to phobos:

Replying to runa:

It will be shipped with the packages, but not inside the packages. The manual explains how to verify the package you downloaded, and also how to extract the package archive. Putting the manual inside the package won't make any sense.

Ok, let's step back. One point of the user manual is to help users without, or with unsafe, web access to torproject.org, to configure tor correctly, and get some basic questions answers.

Another point is to provide "tor in a nutshell with quick debugging tips" for users. This should help explain Tor to new people and maybe reduce support requests.

We need to have the tor manual included with the packages. What's included already is too confusing for most users. If it's not there by default, I imagine few will know how to get it.

I wonder if we're misunderstanding each other here. When I say "it will be shipped with the packages", I mean:

You send an email to gettor@torproject.org with "windows" in the body of the message. You receive windows_en.z and short-user-manual.pdf.

Also, I suggest we update the text on check.torproject.org to say "Hey, if you need help, download this fancy user manual".

We should integrate this with the new check html. Do we do this for failures only? or as the default doc for /docs?

I say we integrate it as the default.

Replying to phobos:

We need to have the tor manual included with the packages.

We could in theory mail the pdf to them along with the package, and put the pdf inside the package. Then if they get the TBB from a friend on a USB key, the pdf is still there.

Runa, is there a TODO list somewhere for what we intend to change on the next iteration?

I still maintain that if the user tries a few debugging approaches and they don't work, it is not "probable" that their network is censoring Tor. It is more probable that they didn't try the debugging approaches right.

Replying to arma:

Runa, is there a TODO list somewhere for what we intend to change on the next iteration?

No. Feel free to create one (or list things here and I'll add it to user/runa/tor-manual.git).

I still maintain that if the user tries a few debugging approaches and they don't work, it is not "probable" that their network is censoring Tor. It is more probable that they didn't try the debugging approaches right.

Sure, but what should we say? "You're doing it wrong"?