Question: “Sections must have the titles listed below, unless otherwise specified” is unclear
wooorm opened this issue · 5 comments
In the spec, the requirements section contains the line: “Sections must have the titles listed below, unless otherwise specified“.
- Does that reference the “Extra sections” part?
- Is this the default so that the spec could later allow alternative names for sections?
- Can you use any heading, as long as you specify in the readme that it’s not compliant?
That does not include extra sessions. It should apply to: Table of Contents, Security, Background, Install, Usage, Contribute, and License. Any other sections are allowed, in the right location (after Usage). You shouldn't be able to rename these, so I'm not sure what I meant by otherwise specified.
What do you think?
Maybe:
Sections must have the titles listed below. Other sections and titles can be included in the document outline between Usage and API.
Usage and API are both optional, so that’s why I added “in the document outline”
Usage isn't optional. API is, though. Between Usage and Maintainers would work?
For people reading along: this is asynchronously discussed here: #66 (comment)
I think this can be closed, the spec is clearer now!