Writing Guidelines

Active voice identifies the subject that has performed the given action; for example:

This style makes the reader more involved and therefore makes it friendlier and more comfortable to read. It also makes the sentence a bit shorter.

There are some exceptions to using the active voice.

To exemplify observe the difference in tone the below sentences;

I/we have defined this feature that can be used to …​

This feature is defined in a way that allows you to …​

Users refer to the documentation to find out how they can achieve the desired. The present simple tense ensures the feeling of walking the user through this process. It also makes the text shorter, more understandable and more comfortable to read than any other tense does.

This makes documents sound more engaging as it involves the user directly.

The use of the second person also removes gender specifics, and credits other contributors (most of the time, multiple people worked on the same thing).

Additionally, it removes you, the creator, from the text, which is something you should be going for.

Even before you sit down and start writing, make sure you are aware of your audience. Does the average person from your target audience know what you are talking about?

If you are unsure, either provide a brief explanation of the concept you are talking about or direct the reader to previous documents. It is better to repeat then to have your readers confused.

Another thing to keep in mind is that you are not writing for a friend; make sure the documents you write reflect that. Avoid using stylistically marked expressions, emojis, etc.

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 you weren’t forced to read through them. The next sentence is the only thing that I wanted to state in this sub-section, so some of your time has successfully been wasted :) (Oh, look, the present simple tense isn’t used here - as it would make no sense. The point? Know why you are doing what you are.).

Get straight to the point and tell the readers exactly what they want to know without wasting their time.

When reading, people usually skim through the content or stop altogether when what they are looking for has been found.

If we don’t make any separation between different parts it all becomes one big blob of text. If we split things too much our readers might miss any essential bits.

Things that make sense together should stay together, something that does not make sense together should not stand together.

A great example of a poorly structured text is the paragraph in the 'Follow the KISS principle' section; no separation, mixing topics…​ Strive to produce a straightforward text the is easy to navigate and logically continuous.

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.

Don’t provide excessive visual material by showing every single step of a process or, even worse, by just pasting a screenshot with no context of what we are looking at.

When including images, make sure to indicate what the image represents and to provide an image caption that outlines what goes on in the image. An image may allow the reader to quickly refresh their memory if they are already familiar with something.

Typos happen. There are a lot of great, free tools, as well as some paid ones, that provide you with various types of suggestions for change and greater grammaticality of the text in production.