Ticket #13004: onionoo-documentation-overview.md

File onionoo-documentation-overview.md, 5.6 KB (added by karsten, 5 years ago)

Onionoo documentation overview, first draft

1# Onionoo documentation overview
3Onionoo needs documentation for users, service operators, and potential contributors.
5Users in this case are not so much end users, but developers of Onionoo clients;
6end users of Onionoo clients should refer to those clients' documentation.
7Service operators are people who run a public Onionoo server.
8Potential contributors are developers who consider writing code for the Onionoo server itself.
10This document outlines what documentation exists or should exist for Onionoo.
12## Documentation for users
14Most Onionoo users who are interested in reading its documentation are developers who write an Onionoo client.
15In addition to that there are a smaller number of people who read user documentation to query Onionoo directly rather than using one of the available Onionoo clients.
16But for the purpose of this document, most users are interested in reading documentation of the RESTful API that Onionoo provides, but they don't care much about its Java sources.
18### Overview
20The starting point for every user and even every potential contributor is the overview page.
21It describes what Onionoo is, lists known Onionoo clients, and points to available documentation for users and potential contributors.
22The product overview must be easily accessible, which is why it is available via `https://onionoo.torproject.org/`.
24The sources of the product overview are available in `web/index.html`.
26### Getting Started guide
28New users of the RESTful API may find it overwhelming to read through the protocol specification before making their first request.
29A tutorial or Getting Started guide would get these users up to speed within 5 or 10 minutes by suggesting some easy requests to make and refine towards getting a desired result.
31There is a small Getting Started guide available at the bottom of `web/protocol.html`.  Maybe it's too well hidden, but it's a start.
33### Protocol specification
35Once a user knows what Onionoo provides, they can read up the details in its protocol specification.
36This document tells them what requests they can make and how to interpret responses.
37Ideally, the protocol specification makes it unnecessary to read up further documentation of Tor descriptors.
38A positive side effect of making Onionoo's protocol specification as precise and useful as possible is that the documentation of Onionoo clients is more likely to be useful.
40The sources of the protocol specification can be found in `web/protocol.html`.
42## Documentation for service operators
44A service operator is a person who wants to deploy the Onionoo server.
45That person wouldn't have to understand the inner workings of the Onionoo code, but would know enough about it to set it up and handle common problems.
47### Deployment Guide
49The Deployment Guide explains how to set up a production environment for running the Onionoo server and how to deploy Onionoo into it.
51There is a somewhat outdated Deployment Guide available in the `INSTALL` file.
52It should be updated, moved to a documentation subdirectory, and linked from the README file.
54## Documentation for potential contributors
56A potential contributor is a person who knows what Onionoo provides and who wants to help write code (or documentation) for the Onionoo server.
58### README
60The README (or README.md) file is the starting point for understanding what's in the source tree.
61It should contain a short description of what Onionoo is, in case the source tree is the first time the reader gets in touch with Onionoo, rather than the overview page.
62The README file should guide the reader by telling them which document to read next for what aspect of the Onionoo sources.
64### Design document
66The design document specifies the operation of the Onionoo server without requiring any knowledge of its source code.
67The existing design document in `DESIGN` was written as part of a (failed) project to port Onionoo from Java to Python.
68This file is now outdated, and maybe should rather be deleted than updated.
69The way how Onionoo operates can also be explained as part of the source code documentation.
71### Source code overview
73A potential contributor shouldn't be forced to read through source code files to understand how these (compiled) files interact with each other.
74There should be an overview of the source code that guides the developer where to start reading.
76There is currently no such documentation available, but it may be possible to write it using JavaDoc's `package.html` and have it integrated into the generated JavaDoc output (which doesn't exist yet).
78### Source code documentation
80Documenting the source code itself makes it easier for a potential contributor to understand what it's doing.
81Source code can be documented using JavaDoc comments for inclusion in the generated JavaDoc output, or using non-JavaDoc comments to be read together with the source code.
83There is currently little source code documentation in Onionoo, simply because the code is self-explanatory!
84More seriously, this needs fixing.
86### Contributor Guide
88The Contributor Guide would tell potential contributors how to write, test, and submit patches.
89This includes setting up a suitable development environment using Vagrant, writing code that conforms to the code style guidelines, up to writing useful commit messages and coming up with a good Git history.
91There is currently no Contributor Guide for Onionoo, but it would be very useful to have one.
92Once it exists it should live in the documentation subdirectory (which doesn't exist yet).
94### Documentation overview
96Last but not least, this document should be part of Onionoo's documentation.
97The purpose is that contributors know what documentation exists, or should not exist, and why.