krita: move to common, update description; style-guide: add description guidelines (#10858)

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
 

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>.