Skip to content

Add a markdown style guide #49

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

Merged
merged 6 commits into from
Feb 14, 2023
Merged

Add a markdown style guide #49

merged 6 commits into from
Feb 14, 2023

Conversation

dyladan
Copy link
Member

@dyladan dyladan commented Oct 11, 2022

@basti1302
Copy link
Contributor

Some other things that come to mind:

  • We could link to https://www.w3.org/Guide/manual-of-style/ at the start of the style guide. Suggestion: "In general, the W3C Manual of Style applies. The following style guide extends it with additional rules."
  • In addition to the comment on how to reference fields, should we also include a comment on kebab case (span-id vs span ID vs SpanId)? Suggestion:

Naming fields

Field names are generally lower case. Fields names consisting of multiple words should be written in kebab case (e.g. span-id). Use code markup (markdown backticks) when referring to field names. Do not use code markup or kebab case when referring to a general concept instead of a specific field name. (e.g. "This is the ID of the operation of the callee (in some systems known as the span ID) and is used to uniquely identify an operation within a trace.")

@basti1302
Copy link
Contributor

@dyladan this has two approving reviews and has been open for a while, I think we could go ahead and merge, WDYT?

There is one pending open question from me but it is not blocking and the suggestions could also be applied later (or never, that's fine, too).

@kalyanaj kalyanaj merged commit 6f7c8f7 into w3c:main Feb 14, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants