Opened 5 years ago

Closed 5 years ago

#13004 closed enhancement (fixed)

Decide what documentation should exist for Onionoo

Reported by: karsten Owned by:
Priority: Medium Milestone:
Component: Metrics/Onionoo Version:
Severity: Keywords:
Cc: iwakeh Actual Points:
Parent ID: Points:
Reviewer: Sponsor:

Description

Onionoo needs documentation for users, service operators, and potential contributors. I started writing a meta document that outlines what documentation exists or should exist for Onionoo. See attached. Happy to discuss on this ticket before I commit this overview document to Git.

Child Tickets

Attachments (3)

onionoo-documentation-overview.md (5.6 KB) - added by karsten 5 years ago.
Onionoo documentation overview, first draft
onionoo-documentation-overview.2.md (6.5 KB) - added by karsten 5 years ago.
Onionoo documentation overview, second draft
onionoo-contributor-guide.md (1.6 KB) - added by karsten 5 years ago.
Onionoo contributor guide, first draft, from #12882

Download all attachments as: .zip

Change History (8)

Changed 5 years ago by karsten

Onionoo documentation overview, first draft

comment:1 Changed 5 years ago by karsten

Cc: iwakeh added

iwakeh, I'm curious to hear your opinion as Onionoo's newest contributor. What documentation did you find useful, what needs updating, what's obsolete, and what were you missing?

comment:2 Changed 5 years ago by iwakeh

Documentation for Users

The getting started guide is a good idea.
Once someone really wants to write a client they will have to read protocol.html (which is very well written and was very useful as a reference when I started working on koninoo).

I cannot make sense of the following sentence (line 38):
A 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.

Documentation for Potential Contributors

FAQs might be useful for things like

  • maven vs. ant
  • Why are certain java libs not up-to-date
  • Which java libs could be used for Onionoo development
  • etc. etc.

(You probably already have a collection of some of these questions anyway?)

It's ok to remove the DESIGN doc. Such docs usually only describe hopes and plans,
but hardly facts. The important decisions should show up in the FAQs and javadoc.

Well, other than that, source code is self explanatory :-)
I agree, javadoc should be added for all interfaces and public methods.
(The, soon to be available, client-api could try to provide that from scratch.)
And, this should be a rule in the contributor guide, too.

Package javadoc is a good place for a overviews.
(btw: Since javadoc 5 it is recommended to use package-info.java, cf. this, search for paragraph Package Comment Files.)

Contributor Guide

In addition to the topics you mention I would propose
Coding Rules or a Design Guide for contributors.

This would contain:

  • naming rules for variables and methods
  • the above mentioned javadoc rule
  • a big no to uses of System.out or System.err as soon as logging is in place
  • rules about when to use external apis
  • and some more.

Maybe a reference to some standard java coding guides for defaults?

comment:3 in reply to:  2 Changed 5 years ago by karsten

Replying to iwakeh:

I cannot make sense of the following sentence (line 38):
A 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.

Here's a rephrased version of that sentence: "A 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."

Thanks for your feedback! I added it to the second version of the documentation overview, attached to this ticket.

Changed 5 years ago by karsten

Onionoo documentation overview, second draft

Changed 5 years ago by karsten

Onionoo contributor guide, first draft, from #12882

comment:4 Changed 5 years ago by karsten

Attached draft of the contributor guide outlined in #12882, which is now closed.

comment:5 Changed 5 years ago by karsten

Resolution: fixed
Status: newclosed

I re-formatted the two documents attached to this ticket and committed them to master. That concludes this ticket which was mainly about deciding what documentation should exist. Again, thanks for your input, iwakeh.

Note: See TracTickets for help on using tickets.