From 0897084ebb7cecbc1655015275db112b5ad5d48c Mon Sep 17 00:00:00 2001 From: Managor <42655600+Managor@users.noreply.github.com> Date: Sat, 15 Mar 2025 20:48:18 +0200 Subject: [PATCH] style-guide: reorder instructions (#15941) --- contributing-guides/style-guide.md | 47 +++++++++++++++--------------- 1 file changed, 23 insertions(+), 24 deletions(-) diff --git a/contributing-guides/style-guide.md b/contributing-guides/style-guide.md index 3038890f71..c9e6e3f654 100644 --- a/contributing-guides/style-guide.md +++ b/contributing-guides/style-guide.md @@ -291,7 +291,7 @@ This can be resolved by inserting a comma before the "and" or "or" in the final ### Special cases -- If a command performs irreversible changes to a file system or devices, +If a command performs irreversible changes to a file system or devices, write every example in a way that cannot be copy pasted thoughtlessly. For example, instead of `ddrescue --force --no-scrape /dev/sda /dev/sdb` write `ddrescue --force --no-scrape {{/dev/sdX}} {{/dev/sdY}}` @@ -300,6 +300,8 @@ This can be resolved by inserting a comma before the "and" or "or" in the final In general, placeholders should make it as intuitive as possible to figure out how to use the command and fill it in with values. +Acronym expansions (i.e. protocols, tools, etc) must not be translated unless there is a recognized native equivalent for them. + Technical wording on description lines should use the `backtick` syntax. Use backticks on the following: @@ -309,8 +311,28 @@ Use backticks on the following: - Standard streams: `stdout`, `stdin`, `stderr`. **Do not** use the full names (e.g. standard output). - Compression algorithms, e.g. `zip`, `7z`, `xz`. +When describing keycaps or a keyboard shortcut for a utility, use the same [keypress syntax](#keypress-syntax) as in example commands. Make sure to enclose it in backticks so that it is not invisible in markdown renderers (i.e. ``Print the last lines of a given file and keep reading it until ``:``). + ## Heading +### Program description + +- 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`) +- If the program name differs from its executable name, it can be named at the start of the heading (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`). + +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 should instead be simplified to make it easier for everyone to read: + +```md +> Change the current working directory. +``` + ### More information links - On the `More information` link line, we prefer linking to the author's provided documentation of the command-line reference or the man page. When not available, use as the default fallback for all platforms @@ -368,29 +390,6 @@ the part of the address that starts with `?view=`. ## Example descriptions -### Wording - -- 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`). -- 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 should instead be simplified to make it easier for everyone to read: - -```md -> Change the current working directory. -``` - -### Formatting - -- Proper names should be capitalized in the description whenever applicable (e.g. use `A tool for interacting with a Git repository.` instead of ``A tool for interacting with a `git` repository.``). -- Acronym expansions (i.e. protocols, tools, etc) must not be translated unless there is a recognized native equivalent for them. -- When documenting keycaps or a keyboard shortcut for a utility, use the same [keypress syntax](#keypress-syntax) as in example commands. Make sure to enclose it in backticks so that it is not invisible to markdown renderers (i.e. ``Print the last lines of a given file and keep reading it until ``:``). - ### Short option mnemonics Short option mnemonics are optional hints that can be added to help users understand the meaning of these short options. The assigned mnemonics should match with the ones in the command's official documentation (e.g. from `man` or `Get-Help`). For example: