From ec81376b20c2a896250b87f093172522042d348b Mon Sep 17 00:00:00 2001 From: Leonard Sheng Sheng Lee Date: Wed, 7 Oct 2026 15:15:27 +0200 Subject: [PATCH] ci/github-script/reminders: improve style guide reminder --- ci/github-script/reminders/docs-styleguide.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/ci/github-script/reminders/docs-styleguide.md b/ci/github-script/reminders/docs-styleguide.md index 7947d5fac888e..db30873ca5bfe 100644 --- a/ci/github-script/reminders/docs-styleguide.md +++ b/ci/github-script/reminders/docs-styleguide.md @@ -1,12 +1,12 @@ -Thanks for contributing to the documentation +Thanks for contributing to the documentation. -Make sure you follow the [documentation style guide](https://github.com/NixOS/nixpkgs/blob/master/doc/styleguide.md), most notably: +Follow the [documentation style guide](https://github.com/NixOS/nixpkgs/blob/master/doc/styleguide.md), especially: -- Show, don't tell: lead with a minimal working example; explanation follows the code. -- No meta-commentary: don't write "This section explains how to…", just do it. -- Imperative mood and active voice: "Run the command", not "The user should run the following command". -- Present tense: "This creates a folder", not "This will create a folder". -- Be confident: no hedging with "should", "might", "typically", "usually". -- Cut filler words: "simply", "just", "easily", "basically"; "to", not "in order to". +- Show, don’t tell. Start with a minimal working example. Explain after the code. +- Avoid meta-commentary. Don’t write "This section explains how to…". +- Use present tense, imperative mood, and active voice. For example: "Run the command," not "The user should run the following command." +- Avoid vague references like "this" when the referent is unclear. Write "This command creates a folder," not "This will create a folder." +- Be direct. Avoid "should", "might", "typically", and "usually". +- Cut filler words like "simply", "just", "easily", and "basically". Use "to" instead of "in order to". -For larger changes, like adding or removing whole sections, ask the NixOS documentation team for a review. +For larger changes, such as adding or removing whole sections, ask the NixOS documentation team for review.