Opened 3 years ago

Last modified 10 months ago

#5811 new task

Review the latest set of changes in the “short user manual”

Reported by: mikeperry Owned by: runa
Priority: normal Milestone:
Component: Tor Browser Version:
Keywords: SponsorO Cc: mikeperry, lunar@…, mrphs
Actual Points: Parent ID: #10974
Points:

Description

The Tor Short User Manual is appears to be written in mentat rather than human, and I find the section ordering and formatting confusing.

I think it could benefit from a Table of Contents, and a few screenshots of what the TBB startup process looks like, and what the various failure modes look like (like blocking and bridge configuration). It probably should also include a brief description of the privacy properties you get from the Tor Browser (See #5294), and some hints on what the new Tor Browser branding actually looks like on your taskbar (so you don't use the wrong browser).

Also, the GPG verification steps need to be improved to contain screenshots, moved to an "Advanced" section, or simply removed. How does one bootstrap trust in the downloaded GPG binary itself, anyway? Seems like useless noise to even mention GPG verification at that point.

Child Tickets

Attachments (1)

short-user-manual_en_noimg-draft.xhtml (10.6 KB) - added by runa 19 months ago.

Download all attachments as: .zip

Change History (18)

comment:1 Changed 3 years ago by mikeperry

One way to improve things is to sit down with your densest, most computer-illiterate relatives and keep changing things until they seem to get it. I went through this process with https://www.torproject.org/download/download-easy.html#warning and it seemed to help dramatically improve it. See http://web.archive.org/web/20110624000303/http://www.torproject.org/download/download.html.en for what I started with.

comment:3 Changed 3 years ago by mikeperry

  • Milestone set to Sponsor Z: March 1, 2013

comment:4 in reply to: ↑ description Changed 3 years ago by runa

  • Cc mikeperry added

Replying to mikeperry:

I think it could benefit from a Table of Contents, and a few screenshots of what the TBB startup process looks like, and what the various failure modes look like (like blocking and bridge configuration). It probably should also include a brief description of the privacy properties you get from the Tor Browser (See #5294), and some hints on what the new Tor Browser branding actually looks like on your taskbar (so you don't use the wrong browser).

I agree that the user manual could benefit from a lot of things, but I really really really want to keep it short. Our users will not bother reading it if it's too long. The idea is that the manual helps users get started with TBB, and they can then browse torproject.org and read more on their own. Maybe I should just throw in some helpful links at the bottom of the page instead?

Also, the GPG verification steps need to be improved to contain screenshots, moved to an "Advanced" section, or simply removed. How does one bootstrap trust in the downloaded GPG binary itself, anyway? Seems like useless noise to even mention GPG verification at that point.

Are there any better options?

comment:5 Changed 3 years ago by karsten

  • Keywords SponsorZ added
  • Milestone Sponsor Z: March 1, 2013 deleted

Switching from using milestones to keywords for sponsor deliverables. See #6365 for details.

comment:6 Changed 2 years ago by lunar

  • Cc lunar@… added

comment:7 follow-up: Changed 19 months ago by runa

Attached is the current draft of the improved user manual. The new manual is a bit shorter and does not contain information about how to verify the digital signature of the Tor Browser Bundle (now #9883) or how to use a SOCKS proxy (now #9884). Thoughts, comments, questions?

Changed 19 months ago by runa

comment:8 in reply to: ↑ 7 ; follow-up: Changed 19 months ago by mrphs

Replying to runa:

Attached is the current draft of the improved user manual. The new manual is a bit shorter and does not contain information about how to verify the digital signature of the Tor Browser Bundle (now #9883) or how to use a SOCKS proxy (now #9884). Thoughts, comments, questions?

Could you push it to git? maybe as a branch of tor-manual.git or something? This would make it a lot easier to commit.

I disagree with taking the whole "Verifying Download" section out, as it is an essential part of this manual. I think we should briefly describe the steps and put a link to a more descriptive manual instead.

comment:9 Changed 16 months ago by mrphs

  • Cc mrphs added

comment:10 Changed 15 months ago by lunar

  • Component changed from Tor Support to Tor bundles/installation
  • Keywords SponsorO added; SponsorZ removed
  • Summary changed from Translate the TSUM into human and improve section organization to Review the latest set of changes in the “short user manual”
  • Type changed from defect to task

comment:11 Changed 15 months ago by lunar

  • Parent ID set to #10974

This ticket contains the latest incarnation of the “short user manual”. It should be reviewed and relevant part of its content be integrated into the Tor Browser User Manual (#10974).

comment:12 Changed 15 months ago by lunar

After a quick look and from memories of a discussion with mttp, here's a review of the structure.

Sections that are not relevant to the Tor Browser User Manual:

  • How to download Tor: either the user will be on the Tor Project's website and able to download the bundle, or they will already be reading the manual they got with the bundle (#10980).

Sections that needs updating:

  • How to use Tor: should probably be retitled How to use the Tor Browser in the process. Things to document are probably the default amnesia of the Tor Browser, what's in the Onion menu, a few things about NoScript and HTTPS Everywhere… probably others.
  • How to upgrade Tor: the Tor Browser Bundle now has an integrated notification mechanism. We can document the manual upgade process and leave room for the automated one (#4234).
  • What to do when Tor does not connect: this should be moved to a troubleshooting section at the end.
  • An introduction to Tor bridges: this should be moved to the section about configuration.
  • Frequently Asked Questions: they should be in the troobleshooting section

Sections that are missing (at least):

  • How to configure the Tor Browser: the configuration wizard must be explained
  • How to get support (#10981)

comment:13 in reply to: ↑ 8 Changed 15 months ago by lunar

Replying to mrphs:

I disagree with taking the whole "Verifying Download" section out, as it is an essential part of this manual. I think we should briefly describe the steps and put a link to a more descriptive manual instead.

After discussing this with Erinn, Moritz, Mike and Linus, they think the Tor Browser User Manual should contain an appendix about verifying the archive. I don't agree, but so be it. At least we can get the file names updated automatically.

comment:14 Changed 15 months ago by lunar

Another (very short) section that we need to have: How to uninstall Tor Browser

comment:15 Changed 15 months ago by lunar

For the Linux version of the manual, it's probably worth documenting how to configure Unity to run shell script: Menu FilesPreferences, Behavior tab, under Executable Text Files, check Ask each time.

comment:16 Changed 10 months ago by erinn

  • Keywords needs-triage added

comment:17 Changed 10 months ago by erinn

  • Component changed from Tor bundles/installation to Tor Browser
  • Keywords needs-triage removed
Note: See TracTickets for help on using tickets.