cdfoundation / cdfoundation/CICD-Cybersecurity
Use more headings for structures with unique numbers
- Dominant language
- HTML
- Stars
- 25
- Forks
- 29
- Avg merge
- 1h 16m
- Merged PRs (30d)
- 1
Description
To me the current headings on the pages seem off in certain places. Take fore example [1.3 Produce Well-Secured Software (PW) Tasks for Code and Prebuild](https://github.com/cdfoundation/CICD-Cybersecurity/blob/1a400f89ccbd8ca7a09af0a49ee33130c77eafd8/content/en/docs/Phase%201/ssdf/ssdf-pw/_index.md)
### Use headings
I expect al PW.1 items to have a heading, so they show up in the Table of Contents sidebar. Also that would create an anchor to link to.
Some pages have that, some don't.
### Use unique numbers
At the moment it is hard to reference any item from the guide, because headings are not unique in name.
I would expect all PW.1 items to have unique names and numbers across the document, for explicit reference.
It would then become 1.PW.1 as an more readable version of 1.3.1. An idea could be to use letters for the phases as well, although it could be confusing. Alternatively the phases could be renamed to a character, like (CP, BD, PD), although that wouldn't work well with sorting.
Besides numbers, there could also be unique names, to prefix with the stage: "Code and Prebuild: Design Software to Meet Security Requirements and Mitigate Security Risks"
I think the changes will be minimal, but will help make the guide more readable and usable. I think there should be some consensus on the changes, to have a target for a pull-request.
Contributor guide
Research direction
Start by reviewing content/en/docs/Phase 1/ssdf/ssdf-pw/_index.md and the existing PW.1 headings and Table of Contents behavior. First get agreement on the numbering and naming scheme, then apply the agreed headings across the relevant guide pages. Done means PW.1 items have headings, unique references, and usable sidebar entries.
Written by the indexing model from the issue text.
Assessment
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100