Opened 2 years ago

Closed 2 years ago

#21379 closed enhancement (fixed)

Metrics-lib web-site

Reported by: iwakeh Owned by: metrics-team
Priority: Medium Milestone:
Component: Metrics/Library Version:
Severity: Normal Keywords:
Cc: RaBe Actual Points:
Parent ID: Points:
Reviewer: Sponsor:

Description

Quote from meeting:

[this should contain]

  • an overview what it is with a link to releases,
  • javadocs,
  • tutorials.

Child Tickets

Change History (8)

comment:1 Changed 2 years ago by karsten

Sounds like a good start. Building upon it, how about:

  • an overview what it is,
  • link to CollecTor,
  • link to releases or release table,
  • change log or link to change log,
  • instructions for verifying releases,
  • javadocs,
  • tutorials,
  • link to sources,
  • link to bug tracker, open bugs and direct link for adding new bug, and
  • link to contributor docs on team wiki page.

comment:2 Changed 2 years ago by RaBe

Just to have something to start with, I built a prototype for the metrics-lib page: metrics-lib.cc-ltd.net

I hope that I have understood correctly that metrics-lib and DescripTor are the same? I wasn't sure how to call it in the logo and in the text...

For now the texts are basically copy & pasted readme files from the lastest DescripTor release.

comment:3 Changed 2 years ago by iwakeh

Looks like a good start!
Yes, the naming is undecided ans confusing :-)

I think javadoc should be separate (i.e. a link to what used to be on javadocs.cc-ltd.net) and maybe reachable from a large button in the jumbo-box.

comment:4 Changed 2 years ago by karsten

RaBe, thanks for starting this by providing another great prototype! I can't think of any major design changes at this point. For example, I second iwakeh's suggestion to add a button for the JavaDocs rather than including something on this page.

But I also think that we should first have a discussion of what content we want to put on this page. For example, it's great that you used README.md and CONTRIB.md as input for this prototype. But we should probably remove most of the contents for contributors and focus on what a new developer would want to know without necessarily becoming a contributor yet.

Another aspect is that we might want to include links rather than actual contents on this page to keep this page static. For example, rather than including the change log (which I suggested above, I know), it would be easier to just include a link to the change log. Otherwise we'll have to either update the website after a new release or automate that somehow. We can always make it more complex later, I'd say.

iwakeh, what do you think about the following sections:

  • DescripTor - A Tor Descriptor API for Java (1 or 2 sentences with an overview what it is, including CollecTor link)
  • Download (link to dist.tpo folder, most important steps for verifying, link to change log)
  • Dependencies ("what you still need to get, or it just won't work"; hint: we don't need JUnit or Hamcrest, but we need Gson and SLF4j)
  • Tutorials ("how you actually use it to get started")
  • JavaDocs (just the link, maybe with > as on CollecTor page)
  • Development (short paragraph with link to sources in gitweb.tpo, bug tracker bugs.tpo, and team wiki page wiki.tpo, link to reproducible builds doc in git when available)

How should we work on the content? Should we check in the current prototype as index.html and edit the content in Git, ideally with separate commits for additions and removals? Or should we put it on a pad and edit concurrently? Or should we first discuss sections and section contents on this ticket before moving elsewhere?

comment:5 in reply to:  4 Changed 2 years ago by iwakeh

Replying to karsten:

..
Another aspect is that we might want to include links rather than actual contents on this page to keep this page static. For example, rather than including the change log (which I suggested above, I know), it would be easier to just include a link to the change log. Otherwise we'll have to either update the website after a new release or automate that somehow. We can always make it more complex later, I'd say.

Yes, better to start with links and static content.

iwakeh, what do you think about the following sections:

Looks good, comment(s) below.

  • DescripTor - A Tor Descriptor API for Java (1 or 2 sentences with an overview what it is, including CollecTor link)
  • Download (link to dist.tpo folder, most important steps for verifying, link to change log)
  • Dependencies ("what you still need to get, or it just won't work"; hint: we don't need JUnit or Hamcrest, but we need Gson and SLF4j)

That should rather be part of the release Readme.md and of course will be mentioned in the basic tutorial, but not a separate section.

  • Tutorials ("how you actually use it to get started")
  • JavaDocs (just the link, maybe with > as on CollecTor page)
  • Development (short paragraph with link to sources in gitweb.tpo, bug tracker bugs.tpo, and team wiki page wiki.tpo, link to reproducible builds doc in git when available)

How should we work on the content? Should we check in the current prototype as index.html and edit the content in Git, ideally with separate commits for additions and removals? Or should we put it on a pad and edit concurrently? Or should we first discuss sections and section contents on this ticket before moving elsewhere?

I prefer the pad solution (the current content is an example and not really useful in git history) and once we have an agreement there add all to git for continuing in the usual way.

comment:6 Changed 2 years ago by iwakeh

An example tutorial from Junit Getting started.
Just simple java command line and very small example classes. And, I think we can even leave out the os type variations and the metrics-lib target group knows how to run java (I would assume).

Last edited 2 years ago by iwakeh (previous) (diff)

comment:7 Changed 2 years ago by karsten

Okay, let's discuss this more on a pad next week, ideally after Wednesday, because of other end-of-month commitments. (Let's sync via email.) And when we have something, we'll move the discussion back here.

comment:8 Changed 2 years ago by karsten

Resolution: fixed
Status: newclosed

There, we now have a metrics-lib page on Metrics. That concludes this ticket. It doesn't mean we can't improve it, though, but that can happen in new tickets. Thanks, everyone! Closing.

Note: See TracTickets for help on using tickets.