Writing Guidelines
Here, we’ll outline the base guidelines that you need to follow when contributing to the documentation.
You can refer to this article or any other article for additional insight.
Use active voice
Active voice identifies the subject that has performed the given action; for example:
To configure external login providers go into the administration panel, authentication and configure …
This style makes the reader more involved and therefore makes it friendlier and * more comfortable to read*. It also makes it a bit shorter which is always a plus!
There are some exceptions when you should not use the active voice:
-
When we are talking about errors it would sound like we are blaming the user!
-
If it makes the sentence much longer.
Use the present simple tense
Users refer to the documentation to find out how they can do something. Let’s give them the feeling like *we are walking them through this process. It also makes it shorter and a bit * more comfortable to read* then with other tenses.
|
When you are describing things where present simple tense doesn’t make sense, you are free to use the appropriate tense. |
Use second person
This makes it sound more engaging as it involves more people than just you and I.
For example:
I have defined this feature that can be used to …
sounds nicer if we reword it to:
We have defined this feature that you can use to …
The use of the second person also removes gender-specific things, and credits other contributors (most of the time, multiple people worked on the same thing).
Follow the KISS principle!
How many times have we given up on reading documentation because it was all just filler text to produce more and more pages? I bet you wouldn’t read these introductory paragraphs if I didn’t force you to read through them. The next sentence is the only thing that I wanted to state in this sub-section, so I’ve successfully wasted some of your time :). Let’s get straight to the point and tell our readers exactly what they want to know without wasting their time.
Let’s get straight to the point and tell our readers exactly what they want to know without wasting their time.
Keep things structured
When reading, people usually skim through the content or stop altogether when we think we’ve found what we are looking for.
If we don’t do any separation between different parts it all becomes one big blob of text. If we split things too much our readers might miss essential bits.
Things that make sense together should stay together, something that do not, should not.
Use admonition
When we want our reader to pay extra attention to something or when we want to provide some helpful tips, don’t hesitate to use admonition blocks.
The reader is more likely to pay extra attention to something important if it is in a lovely red box with the word "Important" next to it.
Use images… sparingly
Don’t go over the top with images by showing every single step of the way or even worse by just pasting a screenshot with no context what we are looking at.
When including images make sure to indicate what the image represents and make sure to provide an image caption that outlines what is going on in the image. It also allows our readers to quickly refresh their memory if they are already familiar with something.
|
Keep in mind that UI changes will require this images to be updated. |