[tor-dev] New documentation for Tor Metrics website

[Karsten Loesing]

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:
> 
> 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".

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.)

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

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