docs: restructure concise evaluating guide, add terminology list

[janderssonse]

This restructure suggestion PR does the following:

The most important:

• Restructures the information (and does not remove any information from the original document) into simple tables with a theme header, and rules-description format. Aims to make the structure for the user clearer, and hit a add sweet spot between between, let's say a formal ISO 270x doc and something aimed at a developer/tech doing assessment.
• In the same mood, tightens up the language making it a bit more imperative, Verify that, Do that, ex.!

Other:

• Adds basic terminology list
• Adds a version table
• Adds a checkbox to that tables, (This is just an idea, and I don't know if I even like it myself, maybe not... let me know). Intended to use as a check-list, for the end user. Stay in, remove it?

This suggestion came from another PR where I asked about translations, and, while translating, I thought I would like to make the structure a bit more clearer in the original document.

[david-a-wheeler]

Definitely prettier! It's also much longer (e.g., when printed). I don't know which is better for people. Does anyone else have any thoughts?

[janderssonse]

Thanks. The terminology list could be removed as it takes up a lot of the new document. Maybe a terminology list could be an idea for a separate md-doc (in the future). But as for now, I could just remove it from the suggestion above.

[gkunz]

I in fact like the new layout, the check boxes and the languages changes. I think that the increase in length is outweighed by the more prominent structure. However, at the end of the day, it is a matter of taste.

Independent of the structure, I made two proposed additions to the content: the Security Baseline and API Stability as a new criterion. Probably we shouldn't mix structural changes and content changes, so I am happy to add them independently to the guide. Still, curious about feedback.

[gkunz]

I have to admit that I don't understand the reasoning behind: "Software with many users or large users may be inappropriate for your use."? This is already part of the original version, so this question is more directed to @david-a-wheeler.

[janderssonse]

Yes, I just used the original. I also think the sentence is not clear, and even that it should be clearer without that sentence. '...use. Widely-used....'

[david-a-wheeler]

I was thinking about the point of You are not Google: "if you’re using a technology that originated at a large company, but your use case is very different, it’s unlikely that you arrived there deliberately; no, it’s more likely you got there through a ritualistic belief that imitating the giants would bring the same riches."

Basically, while software with many users is often capable, it might not be a good match for your use case. You need to choose software relevant to your problem, not just choosing some software because it's the latest fad. The text is an attempt to counter fad-driven development aka Hype Driven Development.

I'm quite open to finding another way to say it.

[david-a-wheeler]

I think this should be a separate issue/PR. Let's not hold up the restructure for rewording this one point. This is the same wording as earlier.

[janderssonse]

Thanks for clarifying, I understand better now. While I understand and agree to the philosophical reasoning - , I wonder if a reader would catch that, without a longer explanation. An idea would be to put the sentence under the "Consider Necessity"-paragraph , and in a more straightforward form? Something in the style of -> Does your use case really motivate the addition, or are there simpler solutions?

But, maybe the whole discussion as you suggest, should be moved to another issue.

[david-a-wheeler]

I've captured this in issue #853 so we can separately discuss & resolve it.

[janderssonse]

Note: If you decide you want the checkbox to stay in, I will change it to '[ ]' instead of the current Unicode character □. The '[ ]' format is commonly used in markdown and makes it easy to tick off items, ie not just for printout. I was in a bit of a hurry when I added the Unicode character column - I should have used '[ ]' from the start.

[agreedSkiing]

Colleague of @janderssonse chiming in. I would recommend to use "real" checkboxes | <ul><li> [ ] </li></ul> | instead of □ if they work in githubs markdown generator. Credit for this goes to https://stackoverflow.com/a/47344640

[gkunz]

Thanks! As the guide is rendered to https://best.openssf.org/Concise-Guide-for-Evaluating-Open-Source-Software, do we know what the output of | <ul><li> [ ] </li></ul> | looks like there?

[janderssonse]

Regarding Checkbox rendering:

I did some further experimentation and investigated both GitHub flavored markdown and the kramdown conversions (the rendering of the markdown in the link above is done with Jekyll, which uses kramdown GFM). I came to the conclusion that a Unicode character is the only solution that works for both cases I.E- rendering with GitHub's native renderer directly, and through Jekyll/Kramdown.

The official GitHub checkbox syntax - [ ] and above suggestion will render a checkbox in GitHub, but not in Jekyll/Kramdown.
Similarly, using an HTML input element would work for Jekyll/Kramdown, but gets removed from the GitHub native rendering as it sanitizes HTML.

So, to summarize, sadly, the best approach to support both cases (GitHub native rendering and Jekyll-kramdown-GFM rendering) seems to be to use a Unicode character checkbox (as is then).

Note:
I confirmed this through local conversion testing with: kramdown --input GFM withcheckboxvariants.md > a.html
(and AI would reach the same conclusion when provided with sufficient context).

[gkunz]

Thanks @janderssonse for looking into this. I also confirmed the same result in the meantime.

[trumant]

The formatting changes seem like a positive improvement for readability/scannability of the content. Thanks for the contribution!

[david-a-wheeler]

We don't need the version number, the date is sufficient. We normally only use dates.

[janderssonse]

We don't need the version number, the date is sufficient. We normally only use dates.

Fixed, versions removed, only using date

[janderssonse]

I have rebased, and fixed most of the suggestions. Questions still:

• should checkbox stay or go?
• should terminology list stay or go?
• should the unclear sentence @gkunz mentions further up under "Usage Metrics" stay or be trimmed?

[david-a-wheeler]

My thoughts:

should checkbox stay or go?

If we can get the checkboxes to "work" online they have some value. We use Kramdown with Jekyll (the default for GitHub Pages). We can modify its configuration, but is there a configuration that makes them "work"? I'm not sure the Unicode checkboxes add much value, but it doesn't matter much to me either way.

should terminology list stay or go?

I think it should stay. Having clear terms' definitions seems useful. Having them at the end means people can see the meat first.

should the unclear sentence @gkunz mentions further up under "Usage Metrics" stay or be trimmed?

You mean "Software with many users or large users may be inappropriate for your use." yes? Let's make that a separate PR. I don't want to hold up this reorg while also trying to rewrite the text, and trying to do too many things at once can be confusing.

[david-a-wheeler]

janderssonse found that Kramdown can't be configured to make this work. At first I thought we could configure Kramdown to make the checkboxes work ("that can't be right!") but I sure don't find a solution either :-(.

[david-a-wheeler]

I found this which uses JavaScript to fix up some things. I'm not sure this effort is worth it: https://thatgurjot.com/til/clickable-checkboxes-on-jekyll-hugo/

[david-a-wheeler]

In the long term we're working on an OpenSSF glossary. Once that has real content we could point off to that for the terminology.

[janderssonse]

janderssonse found that Kramdown can't be configured to make this work. At first I thought we could configure Kramdown to make the checkboxes work ("that can't be right!") but I sure don't find a solution either :-(.

As the checkbox currently seems to be of limited use, and is causing problems for different renderings options..
I tried another idea - removing the checkbox character, leaving the table cell, with the header "Check" instead of checkbox. Still gives the impression to the reader that one should work through this guide and fill in the blanks.

Another option would be that we just remove the Check-cell.

[janderssonse]

Rebased. Any chance of seeing this move forward? :)

What is left is, from what I can tell, are the following actions:

• make a decision to leave an empty cell named check, which avoids any rendering problems for checkbox (done)
• make a decision about the "usage metrics" discussion earlier in the thread.

[gkunz]

Hi @janderssonse. Sorry for the slow response times (Kubecon and other things happened). I support moving this forward and focusing this PR on restructuring the content. Specifically:

• I don't mind having no functioning checkboxes, but I think that adding a "check" column provides value by explicitly encouraging treating this as a checklist. I personally would have called the header "checked" instead of "check" (mainly because at first reading, I was expecting to find a check in this column) but this is very close to bike-shedding.
• let's move my feedback regarding some of the content to another PR - I'll take the action to propose new text once this PR here lands
• I also agree with keeping the glossary for now and move it later if needed.

[gkunz]

LGTM. I propose to move this forward.

[janderssonse]

Thanks, hope kubecon was great. I notice that the markdowlinter complains so will fix that, and also change to your suggestion "Checked". I'll fix it later.

[janderssonse]

I notice that the markdowlinter complains so will fix that, and also change to your suggestion "Checked". I'll fix it later.

Both of them should now be fixed

[david-a-wheeler]

To continue the bikeshedding, maybe Checked should say Done? - it's shorter and I think that's the intent.

[janderssonse]

To continue the bikeshedding, maybe Checked should say Done? - it's shorter and I think that's the intent.

Done... is Done!:)

[gkunz]

Looks good to me. If we get another approving review, I'll merge this PR.

[david-a-wheeler]

The new alphabetic organization seems to suggest that consulting SAFECode’s guide Principles for Software Assurance Assessment (2019) is the first thing to do. Originally this was point 9, as merely something you COULD do. Do we want to emphasize it that strongly?

[janderssonse]

The new alphabetic organization seems to suggest that consulting SAFECode’s guide Principles for Software Assurance Assessment (2019) is the first thing to do. Originally this was point 9, as merely something you COULD do. Do we want to emphasize it that strongly?

How about changing "Utilize established... " to "Consider utililzing established ..." which should make it clear that you could, not should?

[david-a-wheeler]

That helps, but s/utilizing/using/ ("utilizing" is an unnecessarily fancy word).

[janderssonse]

That helps, but s/utilizing/using/ ("utilizing" is an unnecessarily fancy word).

Rebased and utilized! Fixed I meant!

[gkunz]

thanks @janderssonse. I'd like to really get this merged, so I propose doing so. The WG approved the restructure some time ago already.

Now, one last thing: there is a brand bew OpenSSF global glossary now: https://github.com/ossf/glossary

I suggest moving the terms from this doc to that glossary (I am also fine with first merging and then moving things around) @david-a-wheeler ?

[janderssonse]

thanks @janderssonse. I'd like to really get this merged, so I propose doing so. The WG approved the restructure some time ago already.

Now, one last thing: there is a brand bew OpenSSF global glossary now: https://github.com/ossf/glossary

I suggest moving the terms from this doc to that glossary (I am also fine with first merging and then moving things around) @david-a-wheeler ?

Thanks, I removed the glossary for now and will add to the global glossary in seperete PR, after this one is done.

[david-a-wheeler]

Ok. I think we need merge, then improve further, or the bikeshedding will continue forever.