[tor-project] Tor Browser User Manual review

[sajolida]

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#infodesign-10

  - 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!