Reduce emphasis or possibly deprecate the vector format

[ahouseholder]

Since we are moving toward decision points being the primary data objects, this began as a discussion over whether the "vector format" should include data point version information.

On further discussion, the consensus appeared to be that the usefulness of the vector format is in doubt, and the main argument in favor of it was that it resembles CVSS vector representation. But that didn't feel very compelling to the conversants at the time.

So the direction we came up with was to de-emphasize the "vector format" in favor of the .json representation, and encourage people to use words rather than shorthand notation to talk about SSVC decision points and values.

Resolving this issue will involve either choosing to deprecate the vector format entirely, or just de-emphasize it in the docs (perhaps it survives as an example of how to use decision point keys?)

This issue is the driver behind Issue #332

[j---]

I think we can probably de-emphasize in the docs and also maybe not provide tools for going from JSON to "vector format" (partly because it would be a lossy conversion, vector format cannot contain all the info that is in the JSON, so if we provide a tool to convert to it, it will make it easier for people to not just ship around the JSON like they will need to).

[j---]

Are there negative consequences to removing the abbreviated format from the reference docs entirely that we are not prepared to accept? I know we could always look at the content before #451 if we need it back, but just flagging that reduce emphasis and remove are not exactly the same.

[ahouseholder]

Directly answering the question posed:

Are there negative consequences to removing the abbreviated format from the reference docs entirely that we are not prepared to accept?

From a fact-finding standpoint, the following is a consequence of merging #451 as-is:

• If we merge Remove abbreviated format from docs #451 then the javascript calculator has a vector format that we don't explain in any markdown files

That's okay with me as the content is currently already out ahead of the calculator and we're not necessarily trying to resolve that with new calculator features at the moment. I don't know where the "prepared to accept" line lies for others.

But as regards this issue and #451 as currently proposed: I suppose the question is: if #451 represents the "maximal de-emphasis", then "less-than-maximal de-emphasis" would imply something between what is currently there and #451. So what parts should we keep?

I find that a challenging question to answer. The reason I went as far as I did in #451 was that I didn't see how to reduce without basically removing it.

Referring to this https://github.com/CERTCC/SSVC/pull/451/files/e01f6a598e324c2374ed02de95281b9ee8878f41 state:

• the block of text in docs/howto/communicating_results.mdlines 17-65 were just explaining the vector format. There's no "emphasis" per se, just definition. And they're reasonably complete and adequate, so if we have to explain the vector format at all, that text seems sufficient as it is.
• there are a few sentences in that file outside that block that need to change if that block goes away.
• there are a couple lines in docs/topics/future_work.md that only make sense if that explanation still exists.

Other than that, I couldn't really find anywhere that the vector format shows up outside the calculator.

If there's anything concrete to do in response to this issue, I think it's what's currently in #451, plus perhaps a second as-yet unrecorded issue/PR to modify the calculator.

However, if the point of this issue is to remind us that we're thinking about deprecating the vector format, then we can probably just close #451 without merging and then close this issue as it's not otherwise actionable.

I'm not super invested in the outcome, I just think the choice is essentially one of:

1. do nothing now and close this issue and Remove abbreviated format from docs #451
2. merge Remove abbreviated format from docs #451 and accept that the calculator is a bit more out of sync with the docs
3. close this issue but hold Remove abbreviated format from docs #451 indefinitely until a tbd PR modifies the calculator as well, then merge them in rapid succession

An addendum to (1) above could be to also spawn one or more issues to remove the vector from the calculator and come back to pick up the equivalent of #451 later.

Also, late breaking caveat: It might be that I was narrowly defining "de-emphasis" as "remove / make the verbal footprint smaller" and it's entirely possible that adding words would serve to de-emphasize it better. Hadn't really considered that before now. But I'm also not sure what words to add as the existing documentation footprint is mostly just defining the vector format as mentioned above.