Ticket #13004: onionoo-documentation-overview.2.md

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

Onionoo documentation overview, second draft

Line 
1# Onionoo documentation overview
2
3Onionoo needs documentation for users, service operators, and potential contributors.
4
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.
9
10This document outlines what documentation exists or should exist for Onionoo.
11
12## Documentation for users
13
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.
17
18### Overview
19
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/`.
23
24The sources of the product overview are available in `web/index.html`.
25
26### Getting Started guide
27
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.
30
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.
32
33### Protocol specification
34
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 as possible is that Onionoo client developers are in a better position to make the documentation of Onionoo clients more useful for their users.
39
40The sources of the protocol specification can be found in `web/protocol.html`.
41
42## Documentation for service operators
43
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.
46
47### Deployment Guide
48
49The Deployment Guide explains how to set up a production environment for running the Onionoo server and how to deploy Onionoo into it.
50
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.
53
54## Documentation for potential contributors
55
56A potential contributor is a person who knows what Onionoo provides and who wants to help write code (or documentation) for the Onionoo server.
57
58### README
59
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.
63
64### FAQ
65
66FAQs might be useful for things like:
67
68 - Maven vs. Ant: Maven has its own package manager, Ant lets us use Debian packages;
69 - why are certain Java libraries not up-to-date: most recent version shipped with Debian stable;
70 - which Java libraries could be used for Onionoo development: whatever is in Debian stable, but be sure to ask first;
71
72### Design document
73
74The design document specifies the operation of the Onionoo server without requiring any knowledge of its source code.
75The existing design document in `DESIGN` was written as part of a (failed) project to port Onionoo from Java to Python.
76This file is now outdated, and maybe should rather be deleted than updated.
77The way how Onionoo operates can also be explained as part of the source code documentation.
78
79### Source code overview
80
81A potential contributor shouldn't be forced to read through source code files to understand how these (compiled) files interact with each other.
82There should be an overview of the source code that guides the developer where to start reading.
83
84There is currently no such documentation available, but it may be possible to write it using JavaDoc's `package-info.java` and have it integrated into the generated JavaDoc output (which doesn't exist yet).
85
86### Source code documentation
87
88Documenting the source code itself makes it easier for a potential contributor to understand what it's doing.
89Source 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.
90There should be JavaDoc comments for all interfaces and public methods.
91The soon-to-be-available client API could try to provide that from scratch.
92
93There is currently little source code documentation in Onionoo, simply because the code is self-explanatory!
94More seriously, this needs fixing.
95
96### Contributor Guide
97
98The Contributor Guide would tell potential contributors how to write, test, and submit patches.
99This 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.
100
101There is currently no Contributor Guide for Onionoo, but it would be very useful to have one.
102Once it exists it should live in the documentation subdirectory (which doesn't exist yet).
103
104### Coding Rules
105
106A Coding Rules document would contain:
107
108 - naming rules for variables and methods,
109 - JavaDoc conventions,
110 - big _NO_ to uses of `System.out` and `System.err` (as soon as logging is in place),
111 - rules about when to use external APIs,
112 - etc.
113
114This document might refer to some standard Java coding guides for defaults.
115
116### Documentation overview
117
118Last but not least, this document should be part of Onionoo's documentation.
119The purpose is that contributors know what documentation exists, or should not exist, and why.