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 or type 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…
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 operators as the Windows group 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!
- Yes, I know that: