Make MicroProfile spec release javadoc, pdf, html easier to be found

[Emily Jiang]

At JCrete, I got some feedback on MicroProfile: It is difficult to found out the released MP spec javadoc, html, pdf.

The current: you have to go to individual specs and then click on releases. Some releases have links to javadoc, spec html, spec pdf (see here), while other specs have spec html, pdf attached (e.g. metrics, health check see here, you have to download them and then view them.)

Obviously, we need to improve the user experience. I had a brief chat with Ken at MP Config hangout. I propose the following recommendations.

1. For each individual spec, use the MP Config release format, detailed below

In this way, end users don't need to download and the attach the docs, which is potentially error-prone. They can directly click on the links to view the specs, Javadoc etc.

By the way, for the releases (MicroProfile 1.4 and onwards), all released spec javadoc, pdf, html from MicroProrfile 1.4 are listed here. you can edit the release description to add the link to Javadoc, Spec PDF, Spec html.

2. In microprofile.io landing page (which seems to the popular landing page for end users), how about creating a separate page to list the past umbrella releases? Each release consists of individual specs, which should then contain the links to the corresponding Javadoc, Spec PDF, Spec html. I raised this issue to gather requirement and then agree on design. Please comment on the issue if you have any thoughts.

Thoughts?

One problem we have is that all of the artifacts prior to MicroProfile 1.3 (inclusive) are not stored here. Should we upload the older spec docs somewhere else or we treat this as a pity (noop)?

Thanks

Emily

[Ondro Mihályi]

Hi,

We also discussed similar issue during the last Architecture Board call. Amelia suggested that we redesign the projects page at microprofile.io to list information about individual specs and, ideally, link to resources about the latest version of each spec, e.g. javadocs and spec docs.

I think that Emily's ideas and the idea of redesigning the Projects page can be merged. We can either improve the Projects page or replace it with a page about MP spec releases together with info about the other (not yet released) projects.

For a very long time, I've had an idea of the Jenkins release job generate the notes for each release in github so that no manual action in github is needed. This would require some integration with the Github API. But, initially, the Jenkins release job could just produce a text file which could be just copied manually into the release description in Github.

I also think it might be useful if Jenkins also generates an index of all resources in the Downloads area so that the web page could use it to read the information about released specs and its resources. This would mean that the information about MP spec releases on microprofile.io would be always up to date. It would also be transparent for microprofile.io maintainers where to find resources for the latest major MP release and promote it on the landing page.

Ondro

[Emily Jiang]

Thank you Ondro! please also add comments to the page design issue.

Thanks

Emily