From 5afb6ec14e764327b487650031eff3ff5755bb16 Mon Sep 17 00:00:00 2001 From: Lena <126529524+acuteenvy@users.noreply.github.com> Date: Wed, 11 Oct 2023 09:57:23 +0200 Subject: [PATCH] style-guide: add guidelines for `--opt arg`, improve wording (#10906) --- contributing-guides/style-guide.md | 30 +++++++++++++++--------------- 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/contributing-guides/style-guide.md b/contributing-guides/style-guide.md index 8494392a0..82080cce7 100644 --- a/contributing-guides/style-guide.md +++ b/contributing-guides/style-guide.md @@ -109,6 +109,7 @@ Example: - Use GNU-style **long options** (like `--help` rather than `-h`) when they are cross-platform compatible (intended to work the same across multiple platforms). - In other cases, use short options (like `-h`). +- Prefer using a space instead of the equals sign (`=`) to separate options from their arguments (i.e. use `--opt arg` instead of `--opt=arg`), unless the program does not support it. ## Placeholder syntax @@ -175,27 +176,26 @@ to figure out how to use the command and fill it in with values. Technical wording on description lines should use the `backtick` syntax. Use backticks on the following: -- Paths, ex. `package.json`, `/etc/package.json`. -- Extensions, ex. `.dll`. -- Commands, ex. `ls`. +- Paths, e.g. `package.json`, `/etc/package.json`. +- Extensions, e.g. `.dll`. +- Commands, e.g. `ls`. ## Descriptions - - Avoid using the page title in the description (e.g. use `A sketching and painting program designed for digital artists` instead of `Krita is a sketching and painting program designed for digital artists`) unless the program name differs from the executable name (e.g. `rg` and Ripgrep). - Avoid mentioning that the program is used on the command-line (e.g. use `Ripgrep is a recursive line-oriented search tool` instead of `Ripgrep is a recursive line-oriented CLI search tool`). ### Imperative Mood -- **All descriptions have to be phrased in an imperative mood and must be concise.** +- **All descriptions must be concise and phrased in the imperative mood.** - This also applies to all translations by default unless otherwise specified in the language-specific section below. -- For example, when writing documentation for `cd`, a tool to check out and work on a specific directory in the Terminal or Command Prompt, **do not** write lengthy descriptions such as: +- For example, when writing documentation for `cd`, a tool to check out and work on a specific directory in the Terminal or Command Prompt, **do not** write a lengthy description such as: ```md > `cd` is a system tool, available in Windows, macOS, and Linux, to check out a specific directory to get things done in the Command Prompt, Terminal, and PowerShell. ``` -It can be simplified for everyone to read: +It should instead be simplified to make it easier for everyone to read: ```md > Change the current working directory. @@ -205,7 +205,14 @@ If you are afraid the commands may differ between platforms or operating systems In this case, the information of the Windows version of `cd` (stored in `pages/windows/cd.md`) will be displayed by default to Windows users, and a generic/common version (stored in `pages/common/cd.md`) will be displayed for Linux, macOS, and other platforms. -Similarly, when writing examples, instead of `Listing all files:`, `List all files:` can be be used as the example's description below: +When writing descriptions for command examples, **check for any grammatical errors**. `Go to the specified directory` is preferred instead of: + +- `Going to the specified directory` (should not be in present participle form) +- `This command will go to the specified directory` (it is clear that this example works for *this* comment) +- `Let's go to the specified directory!` +- `Directory change` (use the active form instead of passive, if possible) + +For instance, instead of `Listing all files:`, `List all files:` can be be used as the example's description below: ```md - Listing all files: @@ -213,13 +220,6 @@ Similarly, when writing examples, instead of `Listing all files:`, `List all fil `ls` ``` -When writing descriptions for command examples, **check out for any grammatical errors**. `Go to the specified directory` is preferred instead of: - -- `Going to the specified directory` (should not be in present participle form) -- `This command will go to the specified directory` (it is clear that this example works for *this* comment -- `Let's go to the specified directory!` -- `Directory change` (use active form instead of passive, if possible) - ## Serial Comma - When declaring a list of 3 or more items,