[tor-project] Tor Browser User Manual review
sajolida at pimienta.org
Sat Dec 10 16:54:00 UTC 2016
> Hi everyone,
> As some of you may be aware (if you attend the community team meetings),
> Alison and I have been working on updating the Tor Browser User Manual
> and getting it ready for an official release.
> The community team has now had an opportunity to review the manual, and
> now we would like to request feedback from the larger community! You can
> view the manual at https://tb-manual.torproject.org/linux/en-US/ .
> If you find something that needs changing, please open a ticket on
> Trac and set the component to "Community", and the "owner" to "phoul".
For for being sooo late on this one.
Back in August 2015 I spent quite some time sending a detailed review of
the draft to Harmony and Sherief Alaa (but got no answer after that) and
when quickly going through the current version it seems like my comments
ended up in /dev/null. Maybe some are outdated now but I don't feel like
going through the whole thing again and I'm pasting everything here
again. Hope it's useful.
In general, I highly recommend following the GNOME Documentation Style
Guide and others (the Microsoft and Apple style guides are very good
complements as well):
- Avoid future tense, especially in procedures. There are very few
times in technical writing where it is actually needed.
There is a very fundamental reason for using present tense when
documenting procedures. The target audience of readers will be
following the printed procedures as they perform the procedure on
their PC. In this case there is no future, there is only the
present, one present tense action after another. Everything the user
does when following the documented procedures happens now, a
succession of nows, and nothing happens in the future.
- Similarly avoid passive voice. Passive voice is wordy and
cumbersome. For example you have "until Tor Browser is exited or a
New Identity is requested" which could become "until you exit Tor
Browser or request a new identity".
- Avoid long sentences. Limit each sentence to less than 25 words.
Try to split long sentences whenever possible unless that makes your
text too repetitive. Readability studies show that the same content
split into two sentences is easier to comprehend that in a single
- In "about-tor-browser":
- I wonder whether it would be more logical to explain briefly how
Tor works before explaining the security properties that you get
from that functioning.
- Maybe add labels to the image of the Tor network ("exit relay",
"entry node", etc.) like we did on
- "Encryption" is only mentioned in the explanation of the
image. Maybe it should be introduced earlier as a more general
- On the image again, several websites appear as visited from the
same exit node. It would be more accurate to have only one, or one
different exit node for each website.
- Why linking back to "Tor Browser User Manual" at the bottom?
- In "first-time":
- Only one screenshot would be enough to clarify the context and
show the "Connect" and "Configure" buttons. In general I prefer
limiting screenshots to the minimum. See the rational in GDSG:
- Be careful with the word "allow" which is most of the time
wordy and less active than "you can" for example. For example "In
most cases, this option will allow you to connect to the Tor
network without any further configuration." could become "In most
cases, you can connect to the Tor network without any further
- Be careful with "this" and "it" which are often more ambiguous as
intended. We're writing technical documentation and not
literature, so I personally prefer repeating words than risking
ambiguity. For example:
- "In most cases, this option will allow you to connect to the Tor
network without any further configuration." could become "In
most cases, you can click **Connect** to connect to the Tor
network without any further configuration."
- "Once clicked, a status bar will appear, showing Tor’s
connection progress. If you are on a relatively fast connection,
but this bar seems to get stuck at a certain point..." could
become: "A progress bar appears to show the progress of the
connection to the Tor network. If you are on a relatively fast
connection, but the progress bar seems to get stuck at a certain
point...". Here I'm also avoiding Saxon genitive for objects
(Tor's connection) and using more consistent terminology to
refer to the progress bar (avoiding "status bar").
- "a series of configuration options" → "several configuration
- "You will then be taken to the Circumvention screen to configure
a pluggable transport." → "The Circumvention screen appears to
configure a pluggable transport."
- I wonder why you are introducing the notion of "pluggable
transport" here and not the notion of "bridge" instead. Ok, some
pluggable transport don't use bridges, but still the interface
says "Connect with provided bridges"
- Avoid anthropomorphism. For example, in "The next screen asks if
your connection uses a proxy" you're making an anthropomorphism
on "the screen asks". Maybe you can say instead "In the next
screen, you can configure a proxy for your connection".
- Similarly as before, I feel the need to introduce the notion of
bridges which is the one that appears in the interface and with
which people might be more familiar (cf. BridgeDB, etc.). Maybe
you can introduce both?
- Your screenshots are out-of-date already Maybe you can do
You have nothing about installing and verifying Tor Browser. Is that on
- Most of YouTube works with HTML5 nowadays. So maybe your statement
needs to be adjusted. And mentioning HTML5 would be relevant here.
- "Flash is disabled by default in Tor Browser": actually Flash is not
installed at all.
- "Tor Browser includes an add-on called NoScript, accessed through
the “S” icon at the top-left of the window, which allows you to
block it entirely". That's a pretty long sentence. Here you could
split it into "Tor Browser includes an add-on called NoScript,
accessed through the “S” icon at the top-left of the window. With
pages or to block it entirely."
- Maybe say "Adobe Flash" at least once instead of just "Flash" as
"flash" can mean many different things.
- Maybe make it clear that you recommend against installing add-ons
though it's technically possible.
- "correctly, or Tor will not" → "otherwise" maybe?
- I prefer adding optional "that" conjunctions almost
every time possible. Here you're doing it inconsistently in "Make
sure another Tor Browser" and "Make sure that any antivirus
program". "That" makes it less ambiguous and easier to read for
non-native English speaker and translators.
- "Removing Tor Browser from your system is simple": don't say
things are "simple" or "easy". This doesn't bring information and
should be left to the user's appreciation. See "Avoid talking down
to your reader" in GDSG.
That's all for now and keep up with the good work!
More information about the tor-project