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.
@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.
| - Use imperative in direct instructions | |
| - Use imperative in direct instructions | |
| Example: "Add the `python310` package to `buildInputs`" |
There was a problem hiding this comment.
Would be useful to also show what how not to write that sentence.
There was a problem hiding this comment.
| - 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`." |
|
|
||
| [plain language guidelines]: https://www.plainlanguage.gov/guidelines/ | ||
| - Use imperative in direct instructions |
There was a problem hiding this comment.
Would be useful to also show what how not to write that sentence.
|
|
||
| ### Use inclusive language | ||
| - Avoid narrative or discursive style |
| 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.
Should this be an actual permalink then? 😂
Co-authored-by: asymmetric <lorenzo@mailbox.org>
|
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