On 04/09/13 10:19, mercedes508 wrote:
> a draft for feature 5641 has been done by Vidgis, which I added in git
> in order to make it easier to review/merge etc.
>
> I wrote a litlle introduction to Vidgis' draft and almost randomly
> decided to place that file in /doc/advanced_topics/.
>
> Please review that work here:
>
> commit b54502c, doc/explain_why_Tor_is_slow branch, mercedes508
> repo.
Hi,
Thanks a lot for writing this. The content is well structured and very
complete. If I had written it myself it wouldn't have been so detailed.
I like it :)
I'm going to do some changes in the wording. I'm no expert in that field
but those are some things I learned from reading several style guide for
technical writing. As for every creative work, personal taste might
also have its influence. So I'll try to still to changes I can provide
an rational explanation for. Feel free to tell me when I'm going beyond
that and being a control freak.
When writing documentation for Tails I generally try to:
- find the shortest and clearest phrasing for a given idea
- be neutral, avoid personal opinion, humor, jargon, etc.
- apply language tricks that make things easier to translate
1. « Finding the Tor network slow is a very common opinion in Tor
community and Tails' users frequently ask for explanations. »
Tricks:
- Avoid gerund form (finding) and use active and direct
sentences.
- Look for shorter way of explaining the same idea.
So I propose: « Users often find that the Tor network is slow. »
2. « There are many things that combined together slow the Tor network
down, here are a few ones that are quite easy to get without a deep
knowledge in network. »
Tricks:
- Limit each sentence to less than 25 words. [1]
- Don't say things are "easy": avoid personal opinions [2]. What you
might find easy might be difficult for the reader.
So I propose: « This page describes some of the properties of the Tor
network that make it slow. »
[1]
https://developer.gnome.org/gdp-style-guide/stable/fundamentals-2.html.en
[2]
https://developer.gnome.org/gdp-style-guide/stable/fundamentals-3.html.en
3. « As you may know, Tor provides anonymity in building circuits with
three nodes. So when you use Tor and you tried to reach a server,
instead of having only one connection between you and the server, there
are 3 connections which add
[latency](
https://en.wikipedia.org/wiki/Latency_%28engineering%29). »
- I reused the term "destination server" that is already used in the
warning page. I find it more descriptive.
- I'm not sure we need to introduce the term "add latency", I used
instead "takes more time". What do you think?
- Maybe we can reuse the image of the circuit in the warning page. But
maybe that's not needed...
4. « As Tor's anonymity relies in part of the circuits, Tor tries to
build circuits with nodes in different countries which make connection
travel more. This adds another little time. »
- I didn't understand what you meant by « As Tor's anonymity relies in
part of the circuits » but I was happy with the rest of the
explanation so I cut it out :)
- Spell out numbers from zero through nine unless the number is part of
a measurement. [3]/Numbers
[3]
https://developer.gnome.org/gdp-style-guide/stable/grammar.html.en
5. « Node's quality », and « Tor network's misuse »
Trick:
- Replace the genitive construction with an of structure. [4]/Topic 13
So I changed them for « Quality of the nodes », and « Misuse of the Tor
network ».
[4]
https://developer.gnome.org/gdp-style-guide/stable/locale-5.html.en
6. « Tor lacks capacity too. »
Trick:
- I usually use "too" only in front of an adjective, eg. "too slow",
and use "as well" otherwise.
- I'm not sure Tor lacks capacity in general. Having bigger and
faster relay would make the network faster, and of course more
capacity can bring better performance. So I changed that sentence
to mention that idea.
7. « Some Tor users use it to use Peer to peer software »
I'm not against repeating words in general. I usually prefer to reuse
the same terminology instead of using synonyms which might confuse the
reader. But this time I found a phrasing that could avoid that:
« Some people use peer-to-peer software through Tor »
8. "Relay" instead of "node"
I also replace the term "node" with "relay" which I find more descriptive.
So I pushed that into the new branch doc/explain_why_Tor_is_slow. And
added my changes on top of that. Please don't be scared or discouraged
by the color of the diff! It is good to have several people rewrite this
kind of doc several times, and diff often look scary, even though the
result is the addition of all the previous works.
Something else I was not sure about is where to place that do.
Now I'd like someone else to have another look.
I'm not 100 % sure about where to put that page. It is fine where it is
now I think, and it might be overloading the "General information"
section to put it there. But it's not a really "advanced" topic either.
