Style guide for the specification

[handrews]

As I write PRs, I keep finding little things that I'm not sure how to do. Some examples:

• What are the rules about which headings go in the TOC and which don't?
• It seems clear that RFCs are to be written without a space between the "RFC" and the number; are there other conventions to follow?
• RFC referencdes often go to a specific section without noting that section in the text, is that intentional or should we be more explicit in the readable text? I think some do mention section numbers or titles, but I have no idea what's ideal
• Section title capitalization - it seems like we go full title-case, but it would be a good idea to document it
• When referencing a named Object, does it need to always link to the section or only on first mention in a given paragraph / section whatever?
• Similarly, when referencing an RFC multiple times in a section, does every mention need to be a link?
• We should document that we use REQUIRED but not OPTIONAL as came up in a recent PR. Unless we want to follow issue editorial: field not explicitly required can be considered optional #2470 and start using OPTIONAL - we should either do that or close editorial: field not explicitly required can be considered optional #2470
• How do we handle informative vs normative references? (see also issue Add appendix "Informative references" to published spec documents #3740)

There are other things with less impact (e.g. for bulleted lists do we treat bullet points as sentences or not?), but these are the ones that I hit the most.

[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.