-
-
Notifications
You must be signed in to change notification settings - Fork 250
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
recover style guide from CONTRIBUTING.md #698
Conversation
@zmitchell something went wrong a while ago. the changes from NixOS#607 got overwritten with those from NixOS#596
That was intentional, I think there's more information in the style guide now than there used to be. This would remove all of the guidance around header sizes and code blocks. |
The new guide clearly distinguishes between source-level style and writing style as well. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@zmitchell I included back your additions I found got lost in the revert/update.
|
||
[plain language guidelines]: https://www.plainlanguage.gov/guidelines/ | ||
- Use imperative in direct instructions |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
- Use imperative in direct instructions | |
- Use imperative in direct instructions | |
Example: "Add the `python310` package to `buildInputs`" |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Would be useful to also show what how not to write that sentence.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
- Use imperative in direct instructions | |
- Use imperative in direct instructions | |
Example: "Add the `python310` package to `buildInputs`." | |
Counter-example: "Here you may want to use the `python310` package, which has to be added to `buildInputs`." |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
LGTM, just a few nits.
|
||
[plain language guidelines]: https://www.plainlanguage.gov/guidelines/ | ||
- Use imperative in direct instructions |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Would be useful to also show what how not to write that sentence.
|
||
### Use inclusive language | ||
- Avoid narrative or discursive style |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Example?
Use [reference links][ref_links] to keep the source legible. | ||
All links in a section should be grouped together at the end. | ||
For instance: | ||
[permanent links]: https://en.wikipedia.org/wiki/Permalink |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Should this be an actual permalink then? 😂
Co-authored-by: asymmetric <[email protected]>
I think I just prefer the current document to most of these changes. There's clearly defined, separate sections for writing style and markup, and we recently discussed adding a section for actual Nix code and conventions around using Nix in materials on the site. I don't want all of those things mixed together like they are in this PR. There's a few changes that I agree with here e.g. giving an example for "use imperative when giving direct instructions", but the restructuring of the document is a no-go for me. |
This pull request has been mentioned on NixOS Discourse. There might be relevant details there: https://discourse.nixos.org/t/2023-10-05-documentation-team-meeting-notes-84/33877/1 |
@zmitchell something went wrong a while ago. the changes from #607 got
overwritten with those from #596