User:CodingKoopa/Style extensions

Referring to home directory

Both ~ and $HOME are fair game (as per Help:Reading#System-wide_versus_user-specific_configuration), but ~ is more commonplace on the wiki.

Elide part of input

Related to Help:Style#Code_formatting. For output the guidance is to just use ..., but for input I have seen (in the case of QEMU#QEMU_machine_protocol) [...].

References

Related to Help:Editing#External_links.

I place reference links after punctuation, as in https://en.wikipedia.org/wiki/Wikipedia:Manual_of_Style.

Edit summaries

I write summaries in the imperative mood, as if I am writing a Git commit.

Math formulas

Both ic and indentation and/or bold should be okay!

Technology preferences

Although applications are supposed to be treated equally, there are some places where I draw a distinction:

Put Wayland stuff before Xorg stuff.
Put GPT stuff before MBR stuff.
Mainstream DE stuff before tiling WM stuff (I use Sway btw)

Giving commands

Imperative

For any simple commands to the reader, such as the venerable install <package> instruction, the imperative mood without pronouns is good. This is the most terse option. Example from Dracut:

Install the dracut package.

For a sequence of straightforward commands to the reader, the imperative tense is still your friend! You don't really need to make every step a "you must" or "you need to" if all steps are mandatory. Example from Bluetooth:

Download PsTools, and extract PsExec64.exe.

In an administrator instance of a command shell, from the location of the extracted EXE, launch the registry editor.

In the registry editor, navigate to the following registry key:

Finally, in an imperative sentence, "your" is fair game to refer to the user hardware or configuration. Example from Installation guide:

Ensure your network interface is listed and enabled, for example with ip-link(8):
```
# ip link
```
Connect to the network:
Configure your network connection:

Another example from Firefox:

Ensure that your video card is correctly configured for VA-API as described in Hardware video acceleration.
Ensure WebRender is enabled by navigating to about:support and verifying the Compositing value is "WebRender". It is enabled by default in GNOME and other desktop environments [1].
- Ensure you are not running "Software WebRender" as that will not work as of August 2021 [2].

"You"

Constructions like "if you ... then you must" or "you can" are welcome for commands that depend on the reader's situation, configuration, or choice. For unconditional commands that are adjacent to these, "you must" and "you need to" are fine (which are not infinitives but rather parts of declarative sentences). Example from Steam:

You must install the 32-bit version of the OpenGL graphics driver appropriate for your system.
If not already done during installation, you must generate the en_US.UTF-8 locale to prevent invalid pointer errors.
If you need to add library folders or add non-Steam games to your Steam library, install XDG Desktop Portal with a backend providing a file chooser.

Another example from Btrfs, in a Tip:

You can specify compression at the same time using options -c and -L; see #For existing files.

"We"

I like using editorial we (AKA "academic we", "authorial we") if laying out less straightforward steps that require a plan to be explained. This is also great for when you are laying out an example for a procedure that the reader will need to modify for their purposes. Example from udev:

To identify the webcamera, from the video4linux device we use KERNEL=="video2" and SUBSYSTEM=="video4linux", then walking up two levels above, we match the webcamera using vendor and product ID's from the usb parent SUBSYSTEMS=="usb", ATTRS{idVendor}=="05a9" and ATTRS{idProduct}=="4519".

We are now able to create a rule match for this device as follows: <snip>

Here we create a symlink using SYMLINK+="video-cam" but we could easily set user OWNER="john" or group using GROUP="video" or set the permissions using MODE="0660".

Passive voice

The passive voice is awesome when we are characterizing a system rather than just telling the reader what to do. The difference between the two ways of conveying cause-and-effect is: with "you" the cause is the reader ("if you set X to Y"), but with the passive voice, the cause is the system ("if Y is enabled"). The former conveys a deeper understanding, and is preferred if you know what is going on under the hood. Example from General troubleshooting:

Another option is systemd's debug-shell which adds a root shell on tty9 (accessible with Ctrl+Alt+F9). It can be enabled by either adding systemd.debug_shell to the kernel parameters, or by enabling debug-shell.service.

Indirectly giving commands or specifications with the passive voice is NOT recommended, like in PipeWire:

From PipeWire's perspective, one must have the module x11.bell loaded.

Sentence fragments

Sometimes we give instructions in the form of "to X: Y". This can flow nicely when we are giving multiple commands in succession, especially if this is a looser guide. This is also great for just giving usage information (rather than a sequence of commands). Example from EFISTUB:

First, find out the device number where your ESP resides with: <snip>

In this example, 1 is used as the device number. To list the contents of the ESP: <snip>

To view the current boot entries: <snip>