commit 294a6d097505e0d254ee7019d553b89a41643645
Author: iwakeh <iwakeh(a)torproject.org>
Date: Mon Dec 4 11:14:30 2017 +0000
Delete CONTRIB.md.
CONTRIB.md is partially obsolete and the information it contains is already
available on the public web-pages.
---
CONTRIB.md | 89 --------------------------------------------------------------
1 file changed, 89 deletions(-)
diff --git a/CONTRIB.md b/CONTRIB.md
deleted file mode 100644
index 4f36afe..0000000
--- a/CONTRIB.md
+++ /dev/null
@@ -1,89 +0,0 @@
-Contributor's guide to the Metrics website
-
-Dear contributor to the Metrics website. This guide shall help you
-understand the design decisions behind building the Metrics website and
-give you starting points where you should look to make it bigger and
-better.
-
-First of all, let's talk briefly about the scope of the Metrics website,
-which we'll be calling Metrics in the following.
-
- - What Metrics is: Metrics is supposed to provide easy access to Tor
- network data. The typical Metrics user is neither a researcher nor a
- developer and is just looking for an easy way to learn more about this
- Tor network they have been hearing about. Metrics is giving them data
- in visual or tabular form, together with explanations that are easy to
- understand with as little technical language as possible.
-
- - What Metrics is not: The typical Tor researcher or Tor developer would
- probably want to dive deeper into the data to learn even more about the
- Tor network. But in contrast to the average Metrics user they could
- just fetch the original data from CollecTor and run their own analysis.
- Metrics is not trying to be the solution for everyone. If we have to
- choose, we're aiming for simplicity instead of comprehensiveness.
-
-Now let's take a quick tour of the components that Metrics is made of.
-
- - Data-processing modules: The bulk of Metrics code is running in the
- background, invisible to Metrics users. It's the code that takes
- CollecTor data as input and that produces .csv files that are the basis
- for graphs and tables on Metrics. There's usually one such module per
- generated .csv file that focuses on a different aspect of Tor network
- data. All these modules are periodically executed by the system's cron
- daemon, independent of user requests to the website part of Metrics.
- See the modules/ subdirectory for the existing data-processing modules.
- Note that modules don't have to be written in Java even though that's
- currently the case for all of them. The only requirement is that
- there's a shell script to run the module using packages available in
- Debian stable. The remaining components of Metrics are all related to
- its website part.
-
- - Start page: The website part of Metrics is organized into one page per
- metric, which can be a graph, table, data file, or external link, and
- the start page to browse available metrics. Each metric has attributes
- like a descriptive name, one or more tags (relays, bridges, etc.), a
- type (graph, table, etc.), and a level (basic or advanced). All
- metrics are defined in `website/etc/metrics.json` and displayed in the
- table on the start page.
-
- - Graph pages: The bulk of graph pages consist of graphing methods in
- `website/rserve/graphs.R` that are written in R and using the ggplot2
- graphing library. These methods read one or more of the .csv files
- produced by data-processing modules and produce a graph image as
- output. Graphs have a few additional attributes in
- `website/etc/metrics.json` like a description and parameters to
- customize the graph. As of writing this guide, there's one exception
- with the bubble graph which is implemented using JavaScript library
- D3.js and which might soon be generated on the server using Node.js.
-
- - Table pages: Metrics also provides a few aspects of Tor network data in
- tabular form with customization options. Like graphs, the data in
- these tables is provided using R by reading the previously generated
- .csv files. All relevant R code for generating table data is located
- in `website/rserve/tables.R`. Again, there are additional attributes
- in `website/etc/metrics.json` that define what parameters are available
- to customize table contents and how to format results.
-
- - Data pages: While most Metrics user are not expected to run their own
- analyses based on raw Tor network data, some of them might want to look
- deeper into the data they saw in a graph or table. Metrics provides
- all pre-aggregated output from its data-processing modules as
- downloadable .csv files and also documents these file formats in
- sufficient detail for Metrics users to use them.
-
- - Link pages: Metrics is not the only game in town, and it's great that
- other developers take the publicly available Tor network data and
- visualize it in a different way. Metrics acknowledges these efforts by
- adding link pages with thumbnails to make it easy for Metrics users to
- find those external visualizations.
-
- - About page: Most Metrics users have a basic understanding of how Tor
- works, most likely from reading the main Tor website. But Metrics
- should give its users enough explanations to understand where all the
- Tor network data comes from and how that data is used to learn
- interesting facts about the Tor network. That's where the About page
- comes into play. The About page consists of a list of frequently used
- terms and a second list of frequently asked questions. There could be
- more documentation, but more text doesn't necessarily mean that users
- will read more.
-