spdx / spdx-spec

The SPDX specification in MarkDown and HTML formats.
https://spdx.github.io/spdx-spec/
Other
274 stars 133 forks source link

Consider more prominently presenting Annex B in the 3.0 spec documentation #947

Open alilleybrinker opened 2 months ago

alilleybrinker commented 2 months ago

Right now, Annex B is near the bottom of the sidebar navigation for SPDX 3.0, which makes sense, as it's an annex to the main document. However, I think that people looking to understand SPDX, who go to the specification to learn about it, would be better served by being directed to it more prominently.

To break things down a bit, right the SPDX specification is mostly a description of the details of the SPDX 3.0 schema, suitable for people building tools to produce or consume SPDX data. It doesn't do very much to explain the rationale, purpose, or high level construction of an SPDX document, because that's not the goal of the material. This means though that people coming to SPDX without the context or history would be left to either discover Annex B on their own (far down the sidebar), or to seek outside material to understand. This material is (currently) likely to be outdated (for 2.3 or earlier, rather than 3.0) and also would generally be from the perspective of outside parties rather than describing the goals / intents of the SPDX standards group themselves.