Improvement to score metric experience

[bduranc]

Issue Type: Feature Request / Improvement to existing feature

Issue Description: The license-score is critical to being able to quickly determine the completeness and accuracy of a CD component. However, it may be difficult for newcomers (and perhaps even some experienced users) to interpret as currently displayed in the UI.

These suggestions on how to improve the readability of the score is two fold, covering context and general UI enhancements. We'd do this for both the "Described" and "Licensed" scores. However, this proposal primarily focuses on just the "Licensed" score.

Proposal:

1. Add a "/scoreHighBounds" suffix to each of the score metrics.

Why? The score is out of 100, however at first glance no indication of a range bounding is given. This may cause people to ask themselves: Is this just a count of licenses/things found or is it actually a calculated score? What is the difference between "Effective" and "Tools" columns? To those involved intimately with CD, these questions perhaps have definitive answers, but to newcomers it may not be precisely clear.

2. Add a "layman terms" description link to a simplified version of the score metrics document:

The document at https://github.com/clearlydefined/license-score/blob/master/ClearlyLicensedMetrics.md explains the score criteria but is a fair bit to read through.

A simplified version of this document could be created in the same docs repository and we put a link to it at the bottom-right corner of the score tool-tip in the UI.

For this to work, we also need to ensure the documents and naming of score metrics are consistent with how they are named in the UI. I.e. ("Discovered" metric in UI currently corresponds to "File-level license and copyright" metric in the docs)

3. Decrease score tool tip transparency and change "red" to "orange".

The fact that the current tool tip is somewhat transparent, means it blends in with other background text and becomes difficult to read. The current text color for "red" is also hard on the eyes.

For these reasons, I propose...

a) we make the following changes to the tool tip: change the RGB alpha on the tool tip background color to .90%. up from the current of .75%. This will keep it somewhat opaque, but not enough that still blends in with other background text.

b) we change the "red" ( rgb(203, 36, 49) ) text color for each metric to a dark yellow such as hex #eaa927.

Mock-up below: (styling values used are noted above)

[bduranc]

Two other post-submission thoughts that came up in relation to the above:

1. Add a "/scoreHighBounds" suffix to each of the score metrics.

One important part of what is proposed in #1 is the idea that the measure of the score is rather ambiguous, meaning users may be confused if the score figures are a computed weighted score or just a "count of something" (i.e. "# of x" out of "y").

I feel that what is proposed in #1 does not quite address this ambiguity. In fact it may even cause additional confusion by wrongly convincing users that the score is a count of x files out of y files.

One additional improvement would be to suffix a "unit of measure" to the "/scoreHighBounds". An example of such would be to suffix the word "points" or something similar (i.e. 7/25 points).

2. Add a "layman terms" description link to a simplified version of the score metrics document:

An additional improvement would be to make each metric label a hyperlink that will "jump" to the appropriate section in the document proposed in #2 via an "anchor" element (i.e. "#declared", "#consistency", etc.)

[storrisi]

3. Decrease score tool tip transparency and change "red" to "orange".

@bduranc some changes of the color palette where already under development, you can see now how it results

[bduranc]

@storrisi : I noticed. Looks good to me.

[dabutvin]

I think there is still a lot of really good points in here we should go through

[storrisi]

I really glad all of yours suggestions @bduranc , i can start implementing some of them but i'd love to have some feedbacks from @jeffmcaffer and @fossygirl as well.

[storrisi]

@bduranc i really love to go through of this.

In relationship to

2. Add a "layman terms" description link to a simplified version of the score metrics document:

Is there already a text that we can link? If not, who could be able to write it down?

[bduranc]

@storrisi : I was originally thinking we provide a direct link to a "condensed" or "whitepaper" version of this same document: https://github.com/clearlydefined/license-score/blob/master/ClearlyLicensedMetrics.md

There is a lot of good detail in the document, albeit being very extensive. But the different sections are rather dependent on one-and-other, at least how currently written, so I wonder how much we can really condense it and how much it will really make a difference if we did so.

Another idea might be to link directly to the ClearlyLicensed Scoring Formula section of the existing document and make some simple improvements like linking each item in the table to jump to their corresponding sections as each are listed under the ClearlyLicensed Scoring Elements section in the
same document. If we want, we can even go a step further and link those under ClearlyLicensed Scoring Elements to their corresponding headings under the Scoring Elements Discussion section.

As mentioned earlier, we will also need to normalize the terminology used between the documentation and the UI.

For example (hope I got this right),

"Base Score" (Docs) : "Tools" heading (UI)
"Curated Score" (Docs) : "Effective" heading (UI)
"File-level license and copyright" (Docs) : "Discovered" metric (UI)

What do you and others think?

[jeffmcaffer]

Awesome issue. Personally I like the second idea above of enhancing the existing section of the doc to include some more detail/info and facilitate the linking from the UI. The full doc can be linked from further from there. Lets keep it really simple for the normal user and make available the gory detail for those who need/want it.

[storrisi]

I might try to improve the mentioned doc adding links to the elements in the table, and at the same time link the document in the UI inside the Score Renderer. What do you think?

[storrisi]

I've opened clearlydefined/license-score#10 to track the changes to the License doc. Probably @pombredanne is able to merge it?

[bduranc]

@storrisi @pombredanne : Do you think we can close this issue? I think all that remains are alignments to be made in the doc itself. The issue you created under license-score appears to address this.

Thanks.