Style guide / release checklist for the specification about openapi-specification

[lornajane]

• If I had to guess, the TOC hasn't been well-maintained and we should probably regenerate that.
• I don't really want to go back and update the RFC references but good practice is probably to cite the section as well in the link test.
• Title case is fine and we need to improve our markdown automation anyway. Let's document it for now (I know how you feel about our not-contributing file, but maybe let's add a section for style and then we can clean up around it)
• I do not feel it would improve anything for our users if we start explicitly putting OPTIONAL everywhere so I'd like the "just document that we don't do it that way" option, please!

[handrews]

Thanks @lornajane – yeah I don't think we need to go update every RFC citation, but in some areas where I'm already doing PRs that are thick with them, knowing how to handle references to different sections, some of which happen multiple times, would be really helpful.

I'm totally fine with documenting things in the not-contributing file, I've just realized that I'm over capacity and can't take on rewriting that right now even when I'm the person pushing for changes / documented policies :-/ At some point, if no one else steps up, I'll get back to it, but that's multiple months out right now.

[handrews]

Some pre-release checklist items

• re-generate TOC
  • consistent section titling
  • consistent linking
  • update links for GitHub changes done on main
• #3576 (authoritative URL - might need to change specification texgt)
• make RFC links consistent
  • rfc-editor.org vs datatracker.ietf.org
  • different anchor styles (auto-id vs section numbers vs ???)
  • link to sections (always, sometimes, never?) (#3863)
    • section link style: "section x.y" vs "§ x.y" (RFCs seem to use the first style)
• #3740 (informative references)
• Release notes? Blog post?
  • explain how to interpret apparently-but-not-actually-new MUST/SHOULD/MAY/etc.

Plus some "maybes":

• #1720
• #2660

[lornajane]

This is a really great list, that I think we should be expanding to make into a "do it this way" list of style guide directives/tips. We can just keep editing your previous comment and then publish when we're done?