Colin Childs:
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[1] 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.
-----8<-----
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):
https://developer.gnome.org/gdp-style-guide/2.32/gdp-style-guide.html
General comments:
- 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 longer sentence.
- 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 https://tails.boum.org/doc/about/warning/htw2-tails.png.
- "Encryption" is only mentioned in the explanation of the image. Maybe it should be introduced earlier as a more general concept.
- 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:
https://developer.gnome.org/gdp-style-guide/2.32/gdp-style-guide.html#infode...
- 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 configuration."
- 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 options"?
- "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".
In "circumvention":
- 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?
In "update":
- Your screenshots are out-of-date already Maybe you can do without them.
You have nothing about installing and verifying Tor Browser. Is that on purpose?
In "plugins":
- 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 control the JavaScript that runs on individual web pages, or 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 NoScript you can control the JavaScript that runs on individual web 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.
In "troubleshooting":
- "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.
In "uninstalling":
- "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!