Don’t use complicated sentences. Not everyone reading the documentation will be fluent in English, and if the solution texts get translated, it might be to Japanese, which is a language so fundamentally different that anything even a little bit complicated turns into a translation nightmare.
Keep the doc simple from a technical standpoint too. Not everyone reading the documentation will be an experienced admin/user.
They’re just too informal.
The update won’t be available…
The update will not be available…
Avoid passive voice.
This can be fixed by…
You can fix this issue by…
When you tell users to run a set of commands, tell them what is going on. This mostly applies to cases where the documentation text contains some procedure (a set of commands) to do some complicated stuff. When that happens, don’t just put in the commands, but explain them.
$ sudo systemctl disable firewalld $ sudo systemctl stop firewalld $ sudo cp PREUPGRADE_DIR/cleanconf/etc/sysconfig/iptables /etc/sysconfig/iptables
First, disable and stop the firewalld service:
$ sudo systemctl disable firewalld $ sudo systemctl stop firewalld
Then, copy the
cleanconf/etc/sysconfig/iptablesconfiguration file into your system’s
$ sudo cp PREUPGRADE_DIR/cleanconf/etc/sysconfig/iptables /etc/sysconfig/iptables
If this makes the particular documentation too long, you could create a separate page about it and provide a link to the user instead.
If we say things like “this should be in…”, it makes us sound like we don’t even know what’s actually going on.
You should be able to find this list in
The list is located in
In case you want to document one issue for more versions of the product, while there are small differences in each version, create one article for the most current version and use notes to describe differences for other versions.