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.

Sign up for GitHub

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

Jump to bottom

docs: use RFC 2119 keywords #9532

Merged
merged 6 commits into from
Jun 22, 2021
Merged

docs: use RFC 2119 keywords #9532

merged 6 commits into from
Jun 22, 2021

Conversation

robert-zaremba
Copy link
Collaborator

@robert-zaremba robert-zaremba commented Jun 17, 2021 •
edited by ryanchristo
Loading

Description

Recently when discussing NFT standard we stumbled upon the proper use of keywards such as SHOULD, MAY etc ...
Let's add them to our guidelines.

Author Checklist

All items are required. Please add a note to the item if the item is not applicable and
please add links to any relevant follow up issues.

I have...

  • included the correct docs: prefix in the PR title
  • targeted the correct branch (see PR Targeting)
  • provided a link to the relevant issue or specification
  • followed the documentation writing guidelines
  • reviewed "Files changed" and left comments if necessary
  • confirmed all CI checks have passed

Reviewers Checklist

All items are required. Please add a note if the item is not applicable and please add
your handle next to the items reviewed if you only reviewed selected items.

I have...

  • confirmed the correct docs: prefix in the PR title
  • confirmed all author checklist items have been addressed
  • confirmed that this PR only changes documentation
  • reviewed content for consistency
  • reviewed content for thoroughness
  • reviewed content for spelling and grammar
  • tested instructions (if applicable)

@robert-zaremba robert-zaremba added T:Docs Changes and features related to documentation. T: ADR An issue or PR relating to an architectural decision record labels Jun 17, 2021
amaury1093
amaury1093 reviewed Jun 17, 2021
View reviewed changes
docs/architecture/README.md Outdated
Comment on lines 43 to 44


Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

should'nt the markdown linter catch these?

Suggested change

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This should be fixed with make lint-fix. Maybe we should be automatically running this in the CI?

docs/DOC_WRITING_GUIDELINES.md Outdated
@@ -8,6 +8,7 @@
+ Don't abuse `code` format when writing in plain English.
+ Follow Google developer documentation [style guide](https://developers.google.com/style).
+ Check the meaning of words in Microsoft's [A-Z word list and term collections](https://docs.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/term-collections/accessibility-terms) (use the search input!).
+ Use RFC keywords: "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL. They are to be interpreted as described in [RFC 2119](https://datatracker.ietf.org/doc/html/rfc2119).
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I totally agree that we should use these definitions for ADRs, but less sure about docs in general. It might read too much as a formal spec, whereas docs should keep a pleasant side.

My proposal is to remove these definitions for docs, only keep for ADRs.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
+ Use RFC keywords: "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL. They are to be interpreted as described in [RFC 2119](https://datatracker.ietf.org/doc/html/rfc2119).
+ It is recommeneded to use RFC keywords: "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL. They are to be interpreted as described in [RFC 2119](https://datatracker.ietf.org/doc/html/rfc2119).

maybe just a recommendation?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

My proposal is to remove these definitions for docs, only keep for ADRs.

I agree. These keywords are meant for use in RFCs, not in user documentation.

maybe just a recommendation?

I think this would be better but still misleading. I do not think we should be recommending the use of capitalized RFC key words when writing user documentation.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I rephrased it. Could you re-check?

ryanchristo
ryanchristo reviewed Jun 17, 2021
View reviewed changes
docs/DOC_WRITING_GUIDELINES.md Outdated
@@ -8,6 +8,7 @@
+ Don't abuse `code` format when writing in plain English.
+ Follow Google developer documentation [style guide](https://developers.google.com/style).
+ Check the meaning of words in Microsoft's [A-Z word list and term collections](https://docs.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/term-collections/accessibility-terms) (use the search input!).
+ Use RFC keywords: "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL. They are to be interpreted as described in [RFC 2119](https://datatracker.ietf.org/doc/html/rfc2119).
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

My proposal is to remove these definitions for docs, only keep for ADRs.

I agree. These keywords are meant for use in RFCs, not in user documentation.

maybe just a recommendation?

I think this would be better but still misleading. I do not think we should be recommending the use of capitalized RFC key words when writing user documentation.

docs/architecture/README.md Outdated Show resolved Hide resolved
docs/architecture/README.md Outdated
Comment on lines 43 to 44


Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This should be fixed with make lint-fix. Maybe we should be automatically running this in the CI?

ryanchristo
ryanchristo approved these changes Jun 21, 2021
View reviewed changes
docs/DOC_WRITING_GUIDELINES.md Outdated Show resolved Hide resolved
@robert-zaremba @ryanchristo
Update docs/DOC_WRITING_GUIDELINES.md
1676a65 
Co-authored-by: Ryan Christoffersen <12519942+ryanchristo@users.noreply.github.com>
@robert-zaremba robert-zaremba added the A:automerge Automatically merge PR once all prerequisites pass. label Jun 22, 2021
@mergify mergify bot merged commit 856cc5b into master Jun 22, 2021
@mergify mergify bot deleted the robert/rfc-2119-keywords branch June 22, 2021 00:04
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@amaury1093 amaury1093 amaury1093 approved these changes

@ryanchristo ryanchristo ryanchristo approved these changes

@aaronc aaronc Awaiting requested review from aaronc

@alexanderbez alexanderbez Awaiting requested review from alexanderbez

@alessio alessio Awaiting requested review from alessio

@blushi blushi Awaiting requested review from blushi

@clevinson clevinson Awaiting requested review from clevinson

@tac0turtle tac0turtle Awaiting requested review from tac0turtle

Assignees

@amaury1093 amaury1093

@ryanchristo ryanchristo

Labels
A:automerge Automatically merge PR once all prerequisites pass. T: ADR An issue or PR relating to an architectural decision record T:Docs Changes and features related to documentation.
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
4 participants
@robert-zaremba @amaury1093 @ryanchristo @tac0turtle