You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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?
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.
The text was updated successfully, but these errors were encountered:
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!
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.
As I write PRs, I keep finding little things that I'm not sure how to do. Some examples:
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.
The text was updated successfully, but these errors were encountered: