Opened 6 years ago

Closed 6 years ago

Last modified 6 years ago

#9414 closed enhancement (implemented)

Reformat Onionoo's protocol specification to be more useful

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

Description

Christian started reformatting Onionoo's protocol specification, which is great!

Creating this ticket for the discussion.

So far, Christian made two drafts:

Some random comments:

  • It's difficult to compare the two drafts, because the second draft doesn't contain field descriptions.
  • Adding an example is probably not necessary. Instead, we could add a link to /summary?limit=4 for a few actual examples. Same for the other resources.
  • I like the nested tables in the first draft slightly better than splitting up documents into 1 document object and 2 objects for relays and bridges.
  • The colors, including table borders, look slightly better in the second draft.
  • Adding a menu to the left margin is probably overkill.
  • I like both drafts better than the current version, so thanks for working on this!

Child Tickets

Change History (4)

comment:1 Changed 6 years ago by karsten

Christian made a third draft:

Some comments:

  • The "Summary Document" part looks really good. This could be the template for the other three document types.
  • Can you write "field name - field type - required/optional" in that order? The field name is what we care most about, then comes the type, and then the required/optional bit.
  • Can you indent objects like those in the relays array about twice as much as it's the case now? Right now, the columns appear slightly off, but it should become obvious that the "n", "f", "a", and "r" fields are on another level than "relays".
  • The "r" field in both the relays and the bridges objects is a bool or boolean type, not a string. I can fix such things later on. In fact, feel free to leave the types blank if you're unsure, and I'll fill in the types.

So, these are all minor remarks. Would you want to send me a (git-formatted) patch to https://gitweb.torproject.org/onionoo.git/blob/HEAD:/web/index.html, and I clean it up from there? That would be awesome!

Thanks!

comment:2 Changed 6 years ago by karsten

Resolution: implemented
Status: newclosed

Reformatted protocol specification is now merged and deployed. Thanks, Christian! Closing.

comment:3 Changed 6 years ago by gsathya

Oops, I just saw this.

I kinda liked the nav bar on the right. It made it much much easier to navigate since some of these responses have so many fields.

comment:4 in reply to:  3 Changed 6 years ago by karsten

Replying to gsathya:

Oops, I just saw this.

I kinda liked the nav bar on the right. It made it much much easier to navigate since some of these responses have so many fields.

A nav bar has the disadvantage that it wastes space which makes the page even longer. I think the table of contents at the page start is sufficient.

Note: See TracTickets for help on using tickets.