Repository navigation
Conversation
ddbeck
force-pushed
the
data-guidelines-add-mini-style-guide-for-notes/zrxolvszooqt
branch
from
October 6, 2026 10:44
8b7df90 to
989c3f6
Compare
Contributor
|
Tip: Review these changes grouped by change (recommended for most PRs), or grouped by feature (for large PRs). |
ddbeck
force-pushed
the
data-guidelines-add-mini-style-guide-for-notes/zrxolvszooqt
branch
from
October 6, 2026 10:47
989c3f6 to
1c1f552
Compare
caugner
reviewed
Oct 6, 2026
| Notes are the least structured part of browser compat data and the most likely to become stale and outdated. | ||
| Help make the notes easier to maintain by following these style rules: | ||
|
|
||
| - Be specific. |
Contributor
There was a problem hiding this comment.
nit: Should we be bold for readability? (applies to all four)
Suggested change
| - Be specific. | |
| - **Be specific.** |
| - Be specific. | ||
| Avoid shorthands like _supports_, _unsupported_, or _works_. | ||
| Instead, describe the browser behavior or how it differs from expectations. | ||
| For example, write "The method always throws a `TypeError` exception." |
Contributor
There was a problem hiding this comment.
I vaguely remember you preferring to call out the method:
Suggested change
| For example, write "The method always throws a `TypeError` exception." | |
| For example, write "The `example()` method always throws a `TypeError` exception." |
Comment on lines
+31
to
+32
| For example, write "Before version 59, the method always throws…" or "In flex layouts, the `auto` value has no effect." | ||
| Do not write, "The method always throws in versions 59 and earlier" or "The `auto` value has no effect in flex layouts." |
Contributor
There was a problem hiding this comment.
I think it's a good idea to name the browser, rather than just talking about "versions". Otherwise it's easy to miss if a note was accidentally added to the wrong browser.
Suggested change
| For example, write "Before version 59, the method always throws…" or "In flex layouts, the `auto` value has no effect." | |
| Do not write, "The method always throws in versions 59 and earlier" or "The `auto` value has no effect in flex layouts." | |
| For example, write "Before Chrome 59, the method always throws…" or "In flex layouts, the `auto` value has no effect." | |
| Do not write, "The method always throws in Chrome 59 and earlier" or "The `auto` value has no effect in flex layouts." |
Comment on lines
+34
to
+36
| - Cite your sources. | ||
| If a note summarizes a relevant browser bug, release notes text, or other authority, then link to it at the end of the note. | ||
| For example, write "See [bug 1234](#)." |
Contributor
There was a problem hiding this comment.
Should this also mention when to use impl_url, for example with partial_implementation: true and a single note!?
| If a note summarizes a relevant browser bug, release notes text, or other authority, then link to it at the end of the note. | ||
| For example, write "See [bug 1234](#)." | ||
|
|
||
| - Prefer the present tense, even for notes on past behavior. |
Contributor
There was a problem hiding this comment.
nit: Isn't it more than a preference?
Suggested change
| - Prefer the present tense, even for notes on past behavior. | |
| - Use the present tense, even for notes on past behavior. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
This adds a miniature style guide for writing maintainable notes.
Test results and supporting details
None. This is just vibes: the four things that I think make the biggest difference to writing high-quality notes in BCD. I'm open to suggestions here, though I'd like to keep it short.
Related issues
Too various to count, but see BCD v6.0.29 notes audit for extensive discussion of notes quality.