wiki:org/teams/MetricsTeam/Documentation

Version 8 (modified by iwakeh, 3 years ago) (diff)

next step, who writes what.

About This Document

The following structure is the result of Metrics-Team Brainstorming Session which took place April 14, 2016. A request for comments was posted to the metrics mailing list on the same day. As a last step the document was discussed in the metrics team meeting.

Work in progress: So, don't be troubled that there are questions without answers.

Current Step

Answer the questions:

Next Step

Assemble the documentation.


Metrics-Team Documentation Structure

General Goals

We use the wiki to hold documents related to the Metrics-Team and link them from the team page and the project READMEs. Wiki pages look nicer than text files in Gitweb, but there is still a history of the development available. Wiki edits are open to the public, but will be watched and potentially restricted (e.g., write access exclusively for Metrics-Team), in case random people miss-use these documents.

The documentation should answer questions (new) metrics team members might have. The wiki pages should be the first place to look for answers. The wiki pages can be directly linked from the Metrics-Team page and the README's from projects elsewhere.

We came up with an FAQ page that answers questions and refers to more elaborate documentation where necessary. In addition, we want to provide several Guide documents.

FAQ Contents

Possible frequently asked questions grouped by topic in random order.

About the Metrics-Team

  • What projects/products are offered by the M-Team?
  • Where would I start reading about a code base?
  • Who maintains the code repositories?
  • How do I find out what code bases are maintained and where my contribution would be most valuable?
  • Are there statistics on usage (e.g., how many hits does a service like Atlas or Globe get per day)?
  • Which projects could qualify to be added to the Metrics-Team's projects?
  • How do I get involved in metrics team?
  • What skills are required for participating? What tools are used? What languages are supported (maybe even in addition to the languages used in a project)?
  • When and where are team discussions held?
  • Can I write a thesis or do a research project and count on the support of the team?
  • Can I expect somebody of the team to comment on my idea, review my code, or run my service?
  • Where are services currently run, and by whom?

Road-map, Features, and Bugs

This section will also point to the road-map and the release guide.

  • Where can I request a new feature, and when can I expect that to be implemented and deployed?
  • Where do I find open tickets?
  • How do I participate in discussions about new features or existing bugs?
  • What are the plans for further developing existing code bases (road-maps)?
  • How are releases made?
  • How are decisions made about shutting down a service or about removing a feature?
  • Who decides about adding a service?

Contribution and Operation

This section should contain a link to the contributor' guide.

  • How do I submit a patch?
  • Where do I find official sources?
  • Where do I find documentation?
  • Are there code style guidelines?
  • Which external dependencies are allowed, which are discouraged?
  • For people who like to operate a service: how to get started?
  • How are patches reviewed?
  • Can I help by reviewing code or patches?
  • Can I help by running services, either as backup or primary if Tor does not host one of its services (anymore)?
  • What tools are available to ensure that services keep running correctly?
  • Is there a testing policy?
  • Where can I find tutorials on answering simple questions with e.g. metrics-lib?

Funding

This topic's concerns more than just the Metrics-Team. It might belong elsewhere in the Tor Project.

  • Can I get paid for contributing?
  • Can I help find funding for something I'd like to work on?
  • Can I bring my own funding, or can I volunteer, and what can I expect from the team in exchange?

Guide Documents

Some of the main guide documents were already partially or completely written in some Metrics Projects (like Onionoo or metrics-lib). During the course of writing we noticed that many topics and answers are valid independently of the project. Thus, they should be in a central location. These guide documents are in particular:

  • Contributor Guide incl. Coding Style guides
  • Operator Guide
  • Release Guide