Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Style guide / release checklist for the specification #3785

Open
handrews opened this issue May 6, 2024 · 8 comments
Open

Style guide / release checklist for the specification #3785

handrews opened this issue May 6, 2024 · 8 comments
Assignees
Milestone

Comments

@handrews
Copy link
Member

handrews commented May 6, 2024

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 references 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
  • RFC references use a mix of URLs, some pointing to "old-style" text-ish formatted renderings, some to modern renderings
  • 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.

@handrews handrews added this to the v3.0.4 milestone May 6, 2024
@lornajane
Copy link
Contributor

  • 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
Copy link
Member Author

handrews commented May 6, 2024

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 handrews changed the title Style guide for the specification Style guide / release checklist for the specification May 28, 2024
@handrews
Copy link
Member Author

handrews commented May 28, 2024

Some pre-release checklist items

Plus some "maybes":

@lornajane
Copy link
Contributor

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?

@handrews
Copy link
Member Author

Something that's important to keep in mind for a style guide / release checklist:

  • When writing PRs to add new content, the important thing is to get the content in, particularly if the PR is coming from someone who knows more about the area than anyone else available. At this stage the style is not important. If we have a style guide, we can reference that, but do not kill PRs or discourage contributors with endless revisions that area a matter of opinion or stylistic preference.
  • After the PRs for a release are in, other people should go over the whole thing for consistency and tone. Those are different skills than are involved in just getting the content in. It's also important, and too-often neglected, but you cannot do this step until you have all of the content and are sure that your style/tone changes are applied consistently throughout. Never mix these steps!

@handrews
Copy link
Member Author

We also now have numerous issues about updating this or that reference that really need to be governed by a policy and not ad-hoc discussions:

@ralfhandl
Copy link
Contributor

Maybe add

  • Avoid the deprecated <a name=... and instead use <span id=..., placing the link target text inside the <span> element

@lornajane
Copy link
Contributor

I ticked off the items about the table of contents since we no longer need that. And I suggest that the versioning wording is something that covers all our needs and unless there's a big problem we identify with it, it shouldn't be a high priority for taking our time and energy.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
Status: In Progress
Development

No branches or pull requests

3 participants