[Discussion]: Add rationale for each capability

[manics]

Summary

Add rationale for each capability to make decisions visible

Source

Discussions about how the specification is linked to the survey, cafes, etc

Detail

The spec will be changed over time, which inevitably involves revisiting previous decisions. This requires knowledge of the rationale behind each capability, without relying on people's memories, or trawling through 100s of GitHub issues.

Suggestion: For each capability add either a rationale column, a footnote, or similar, stating the decisions behind the capability. This is not intended to be a comprehensive description of everyone who contributed to the decision, but rather a summary of the key points.

The general idea is that someone reading the spec can succinctly see the capabilities and rationale for them. This is not intended to be a full provenance trail- although interesting that will add too much unnecessary information to the spec.

Intended Output

Addition of rationale (key decisions) for each capability to the spec.

Who can help

No response

[JimMadge]

I think this is very worthwhile, to add context for readers and help explain decisions.

MyST supports footnotes.

I think it would be good to not keep this information next to the capabilities (e.g. in a table column) so that they are not to verbose.

[harisood]

@craddm has done some awesome work with the free-text responses, as in #134

Could we signal issues like this and then cross reference in the spec?

[JimMadge]

Could we signal issues like this and then cross reference in the spec?

If it adds context or better explains the spec, I would prefer to include a summary in the specification document itself. Asking people to read through comment chains in issues will be jarring and possibly confusing.

[harisood]

Sorry yeah I meant in the spec! This also links to ongoing work in #157