Install a browser spell checker!
It deosn’t mettar how good yuor psot is technicaly, but if it cnotians speling and gramer erors all over the plais, yuor post will be itnreperted as low-kwaliti as the errors in italics on this line demonstrate.
Ensure your post is readable
This might seem like a no-brainer, but a “wall of text” is not readable, nor are inconsistent italics,
Boldsmall and big font usage.
It doesn’t matter whether you use:
### Extra Bold
headers to subdivide text, as long as you use the same system throughout your tutorial and please use different sizes for different (sub)sections…
Even a simple Bold
**Bold**like in this Guide is sometimes good enough.
If your post is longer than one screen,
Click the triangle
[details="Title"] [/details]markdown to hide text that is too long.
Use correct indentation!
Sometimes it’s just a matter of adding 2 spaces in front of a few lines (E.G. The details section above) to ensure the alignment is correct
E.G. This line is wrongly indented and it decreases the readability of the entire post!
When writing a tutorial, the first line must contain a difficulty
**Difficulty: ★☆☆☆☆**and assign it to a shortcut or whatever you use for automatic comments. Then cut the ★ and replace some of the ☆ with one or more ★ keeping 5 stars in total.
Click the Triangle to have some more examples
- Difficulty: ☆☆☆☆☆: Dead easy. I.E. Nothing to install, just run, type or read something
- Difficulty: ★☆☆☆☆: Just one program to install from the standard repositories, simple tutorial
- Difficulty: ★★☆☆☆: Just one program to install from the AUR or 2 from standard repositories, simple tutorial.
- Difficulty: ★★★☆☆: Not for N00bs
- Difficulty: ★★★★☆: Definitely not for N00bs.
- Difficulty: ★★★★★: you need to modify the kernel code yourself depending on non-obvious parameters and then recompile the kernel and install it yourself…
Be neutral and succintive. E.G.
Don’t say: I’ve tested this on my machine with a Z80 and 64 KB of RAM
Do say: This tutorial has been tested on a Z80 with 64K
Don’t say: After a long and tedious testing phase, which involved rain dances, alchemy and astrology, I found out that the discharge setting for the flux capacitor in
/etc/flux.cfghad to be set to 1 KiloCochrane per second.
sudo nano /etc/flux.cfg
Search for the parameter
Change the value to:
- Don’t say: I’ve tested this on my machine with a Z80 and 64 KB of RAM
Please, please, please use the 3 backticks ``` at the beginning and end of multiple lines of code/text or use 3 or more spaces to indent code and don’t put any
$prompt because then:
a little icon shows up above the command / code that allows the end-user to easily copy the code allowing for less mistakes while copy-pasting! E.G.
echo "The quick Brown fox jumped over the lazy dog
(Hover over the previous
echocommand to see this in action!)
Please use Manjaro commands (
inxi) instead of Arch commands (
lspci, …) wherever possible.
Consistently use the
<kbd>HTML directive for:
- On-screen buttons like OK and Cancel
- Keys on the keyboard like Ctrl+Alt+F2
- Menu settings that have to be clicked like:
- File, Print, Settings
- System Settings, Screen, Compositor
Re-read your post at least twice and edit out any errors you see.
Optional: This is just a gripe of me personally and subjectively:
Use long-format options when posting for N00bs, please!
Click the triangle to read more on the optional requirement
- Yes, I know that:
is the exact same as
inxi --admin --verbosity=7 --filter --no-host --width
- But the former is black voodoo to most N00bs whereas the latter one will tell them that you want:
there is lots of information coming
Some stuff gets filtered
No host information will be given (In this case: host name)
Something with width (in this case: wrap lines when reaching end of terminal width)
Why is this a gripe of me personally you ask?
Well, In my past I’ve been a *nix admin where the *nix group decided to use the same human operators that the Windows group was using already, so we could have a good night’s sleep instead of being called out of our beds all of the time.
These operators used to make tons of mistakes as it’s easy to type 1 (one) letter wrong when following a process, but it’s hard to type an entire word wrong, so we standardized on long parameters for everyone .
That is: for personal use, anyone could use anything they liked, but if you put a command in a script or in a process or a manual you had to use the long version!
Result: Human Errors went down 90% and some scripts that sometimes misbehaved when Mars and Jupiter were in alignment suddenly had no issues any more!
Sometimes using a combination of random letters can form words and some words are quite offensive and some are outright illegal in some countries, so asking for a:
to let’s say the wrong will ensure you get arrested the moment you cross the German border as it’s illegal to call someone a Nazi in Germany without proof he/she is, indeed, a member of the NSDAP… ¹
P.S. For more information on markdown, send a private message @discobot and type
start advanced tutorial (or your local language version of that) or have a look over at CommonMark…
Note 1: As this is for educational purposes only, what I wrote is allowed though.