From 6e0a21c58b9a7ba981671fa70be274e956268e9b Mon Sep 17 00:00:00 2001
From: Lena <126529524+acuteenvy@users.noreply.github.com>
Date: Mon, 9 Oct 2023 14:12:47 +0200
Subject: [PATCH] krita: move to `common`, update description; style-guide: add
 description guidelines (#10858)

---
 contributing-guides/style-guide.md | 43 +++++++++++++++++++++++++++---
 pages/{linux => common}/krita.md   |  2 +-
 2 files changed, 40 insertions(+), 5 deletions(-)
 rename pages/{linux => common}/krita.md (84%)

diff --git a/contributing-guides/style-guide.md b/contributing-guides/style-guide.md
index bdf5a8f2d..8494392a0 100644
--- a/contributing-guides/style-guide.md
+++ b/contributing-guides/style-guide.md
@@ -29,7 +29,7 @@ Example:
 ```md
 # krita
 
-> Krita is a sketching and painting program designed for digital artists.
+> A sketching and painting program designed for digital artists.
 > See also: `gimp`.
 > More information: <https://docs.krita.org/en/reference_manual/linux_command_line.html>.
 
@@ -179,11 +179,46 @@ Use backticks on the following:
 - Extensions, ex. `.dll`.
 - Commands, ex. `ls`.
 
-## Imperative Mood
+## Descriptions
 
-- Example descriptions have to be phrased in imperative mood.
-- For example, use `List all files` instead of `Listing all files` or `File listing`.
+
+- 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.**
 - 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:
+
+```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:
+
+```md
+> Change the current working directory.
+```
+
+If you are afraid the commands may differ between platforms or operating systems (e.g. Windows vs macOS), most [tldr pages clients](https://github.com/tldr-pages/tldr/wiki/tldr-pages-clients) will choose the most suitable version of the command.
+
+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:
+
+```md
+- Listing all files:
+
+ `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
 
diff --git a/pages/linux/krita.md b/pages/common/krita.md
similarity index 84%
rename from pages/linux/krita.md
rename to pages/common/krita.md
index 5dd3b31b9..f13cf5a4a 100644
--- a/pages/linux/krita.md
+++ b/pages/common/krita.md
@@ -1,6 +1,6 @@
 # krita
 
-> Krita is a sketching and painting program designed for digital artists.
+> A sketching and painting program designed for digital artists.
 > See also: `gimp`.
 > More information: <https://docs.krita.org/en/reference_manual/linux_command_line.html>.