Dear list,
writing documentation is hard work. I'm sure you already knew that, but let me re-assure you that I now believe it, too. At least until I forget it again and carelessly start documenting something else that looks tiny and friendly and trivial to document.
Anyway, I spent the last day (felt like half a week) on rewriting the relevant text for the Tor Metrics website, and I wrote a short glossary of terms I didn't want to explain over and over.
Would people on this list mind reviewing my text and suggesting improvements?
For reference, the old text and real graphs, tables, etc. are still available here:
https://metrics.torproject.org/
The new text with sample graphs and the glossary are here, conveniently packaged into a single HTML page:
https://people.torproject.org/~karsten/volatile/metrics.html
I'd be happy for any suggestions here or off-list, either as comments, patches, or edited HTML files. Whatever works best for you works for me.
I'll update the .html file whenever I include suggestions. I hope to put the new text on the real Tor Metrics next week.
Thanks in advance, much appreciated! In fact, I'm pretty sure that all future visitors of Tor Metrics will appreciate your efforts.
All the best, Karsten
Dear Dr. Loesing,
I have a concern about the consensus_weight. The definition of it seems that the consensus_weight is a completely measured value by the authorities. However, from the Bandwidth Scanner Specification, if I understand correctly, it looks like a combination of observed bandwidth and the measured bandwidth. This is the description about how to calculate the consensus weight in the Bandwidth Scanner Specification, "we compute an average of the filt_bw fields over all nodes we have measured. These averages are used to produce ratios for each node by dividing the measured value for that node by the network average. These ratios are then multiplied by the most recent observed descriptor bandwidth we have available for each node, to produce a new value for the network status consensus process."
If I am wrong, could you please let me know? Thank you very much!
Best, Lei
On Fri, Nov 21, 2014 at 12:09 PM, Karsten Loesing karsten@torproject.org wrote:
Dear list,
writing documentation is hard work. I'm sure you already knew that, but let me re-assure you that I now believe it, too. At least until I forget it again and carelessly start documenting something else that looks tiny and friendly and trivial to document.
Anyway, I spent the last day (felt like half a week) on rewriting the relevant text for the Tor Metrics website, and I wrote a short glossary of terms I didn't want to explain over and over.
Would people on this list mind reviewing my text and suggesting improvements?
For reference, the old text and real graphs, tables, etc. are still available here:
https://metrics.torproject.org/
The new text with sample graphs and the glossary are here, conveniently packaged into a single HTML page:
https://people.torproject.org/~karsten/volatile/metrics.html
I'd be happy for any suggestions here or off-list, either as comments, patches, or edited HTML files. Whatever works best for you works for me.
I'll update the .html file whenever I include suggestions. I hope to put the new text on the real Tor Metrics next week.
Thanks in advance, much appreciated! In fact, I'm pretty sure that all future visitors of Tor Metrics will appreciate your efforts.
All the best, Karsten _______________________________________________ tor-dev mailing list tor-dev@lists.torproject.org https://lists.torproject.org/cgi-bin/mailman/listinfo/tor-dev
On 21/11/14 23:05, Lei Yang wrote:
Dear Dr. Loesing,
I have a concern about the consensus_weight. The definition of it seems that the consensus_weight is a completely measured value by the authorities. However, from the Bandwidth Scanner Specification, if I understand correctly, it looks like a combination of observed bandwidth and the measured bandwidth. This is the description about how to calculate the consensus weight in the Bandwidth Scanner Specification, "we compute an average of the filt_bw fields over all nodes we have measured. These averages are used to produce ratios for each node by dividing the measured value for that node by the network average. These ratios are then multiplied by the most recent observed descriptor bandwidth we have available for each node, to produce a new value for the network status consensus process."
If I am wrong, could you please let me know? Thank you very much!
Hi Lei,
thanks for your feedback. You're correct that the consensus weight is based on observed and measured bandwidth. The definition I wrote was an attempt to put the consensus weight, which is to some extent verified by third parties, in contrast to advertised/observed bandwidth, which is entirely self-reported by relays. Let me try to make the definition slightly more correct without making it unnecessarily complex:
""" consensus weight: value assigned to a [relay] that is based on bandwidth observed by the relay and bandwidth measured by the [directory authorities], included in the hourly published consensus document, and used by [clients] to select relays for their [circuits]. """
Does this definition sound okay? Anything else I can tweak?
Obviously, this definition is not as precise as the definitions given in the Bandwidth Scanner Specification. The idea is that whoever reads specification documents doesn't need to read the shorter definitions on the Tor Metrics website. But at the same time people shouldn't get confused by oversimplified definitions.
Again, thanks for your input!
All the best, Karsten
Karsten Loesing:
Dear list,
Dear Karsten!
writing documentation is hard work. I'm sure you already knew that, but let me re-assure you that I now believe it, too. At least until I forget it again and carelessly start documenting something else that looks tiny and friendly and trivial to document.
Thank you for spending time on this.
Anyway, I spent the last day (felt like half a week) on rewriting the relevant text for the Tor Metrics website, and I wrote a short glossary of terms I didn't want to explain over and over.
Would people on this list mind reviewing my text and suggesting improvements?
I had a look through and I didn't make any drastic changes, just picked a few small nits. I attach a patch file for your reading pleasure. Let me know if you disagree with anything or my changes have made things even less clear.
Two comments:
1. "Statistics include subsets of relays or bridges by...country code (only relays and only until February 2013)..."
Do you mean here "from the beginning of time until Feb '13" or "from present day back as far as Feb '13"? I guess it would be clear from context, but I understood the former; if the latter is meant then maybe "as far back as" instead of "until".
2. You might include a definition of "consensus", since although it is a technical term, it is not intuitive and comes up a few times in the rest of the text. I haven't put it in the document in order to preserve the line count but maybe it could go like this, if you wanted it:
<a name="consensus"></a><p><b><a href="#consensus">consensus:</a></b> a single document compiled and voted on by the <a href="#directory-authority">directory authorities</a> once per hour, ensuring that all <a href="#client">clients</a> have the same information about the <a href="#relay">relays</a> that make up the Tor network.
with a link to the same entry where "consensus" appears elsewhere.
That's it.
Thanks in advance, much appreciated! In fact, I'm pretty sure that all future visitors of Tor Metrics will appreciate your efforts.
Thanks for writing the documentation!
Harmony:
I had a look through and I didn't make any drastic changes, just picked a few small nits. I attach a patch file for your reading pleasure. Let me know if you disagree with anything or my changes have made things even less clear.
I attach a better patch file, following advice that I am behind the times with regard to use of the diff command.
On 24/11/14 18:58, Harmony wrote:
Karsten Loesing:
Dear list,
Dear Karsten!
Dear Harmony!
writing documentation is hard work. I'm sure you already knew that, but let me re-assure you that I now believe it, too. At least until I forget it again and carelessly start documenting something else that looks tiny and friendly and trivial to document.
Thank you for spending time on this.
Anyway, I spent the last day (felt like half a week) on rewriting the relevant text for the Tor Metrics website, and I wrote a short glossary of terms I didn't want to explain over and over.
Would people on this list mind reviewing my text and suggesting improvements?
I had a look through and I didn't make any drastic changes, just picked a few small nits. I attach a patch file for your reading pleasure. Let me know if you disagree with anything or my changes have made things even less clear.
Fantastic! Thanks a lot for the edits. I applied them and made a few minor tweaks. All in all your changes make things a lot clearer than before. Much appreciated!
Two comments:
- "Statistics include subsets of relays or bridges by...country code
(only relays and only until February 2013)..."
Do you mean here "from the beginning of time until Feb '13" or "from present day back as far as Feb '13"? I guess it would be clear from context, but I understood the former; if the latter is meant then maybe "as far back as" instead of "until".
The former. But the latter would also be plausible. So there's not much context that people could use to infer what's meant. If you have any suggestions for making this clearer, I'm happy to change the text. (Of course, people can also look at the .csv file to see what they got.)
- You might include a definition of "consensus", since although it is a
technical term, it is not intuitive and comes up a few times in the rest of the text. I haven't put it in the document in order to preserve the line count but maybe it could go like this, if you wanted it:
<a name="consensus"></a><p><b><a href="#consensus">consensus:</a></b> a single document compiled and voted on by the <a href="#directory-authority">directory authorities</a> once per hour, ensuring that all <a href="#client">clients</a> have the same information about the <a href="#relay">relays</a> that make up the Tor network.
with a link to the same entry where "consensus" appears elsewhere.
Great, added.
That's it.
Cool! I updated the text here:
https://people.torproject.org/~karsten/volatile/metrics.html
If anybody wants to do another review round, feel free to send me updates based on that version.
I also put the new text on Tor Metrics:
https://metrics.torproject.org/
Thanks in advance, much appreciated! In fact, I'm pretty sure that all future visitors of Tor Metrics will appreciate your efforts.
Thanks for writing the documentation!
Thanks for reviewing it!
All the best, Karsten
Karsten Loesing:
- "Statistics include subsets of relays or bridges by...country code
(only relays and only until February 2013)..."
Do you mean here "from the beginning of time until Feb '13" or "from present day back as far as Feb '13"? I guess it would be clear from context, but I understood the former; if the latter is meant then maybe "as far back as" instead of "until".
The former. But the latter would also be plausible. So there's not much context that people could use to infer what's meant. If you have any suggestions for making this clearer, I'm happy to change the text. (Of course, people can also look at the .csv file to see what they got.)
I think it reads fine, I just wrongly assumed that we were talking about a newly-introduced statistic rather than one that Metrics had stopped counting.
Thanks for reviewing it!
No problem!
On 28/11/14 06:06, Virgil Griffith wrote:
At the top of the page,
*And if you come across something that is missing here, please let us know.
For "let us know", put an href to an email address/contact-info for submitting ideas.
Indeed, good catch. I'm currently talking to other Tor devs to find the right email address or contact info to put there. Thanks for the suggestion!
All the best, Karsten
-
Harmony -
Karsten Loesing -
Lei Yang -
Virgil Griffith