User guide style guide

The way you structure information in your guide impacts how easily users can find what they need at just the right time. There are several structural elements to make information more accessible:

A good document structure allows users to find the information they’re looking for through skimming. You can achieve this by using headings, lists and tables. Also, start with general information, requirements and setup information before becoming more specific.

Adding sections to your user guide lets you employ a table of contents. A table of contents gives users an overview of everything covered in the guide at a glance.
While Markdown has no such feature by default, your IDE probably has an extension to generate a table of contents automatically, for example markdown-toc (Atom) or Markdown-TOC (Visual Studio Code).

Use links to provide readers with general additional information, which is not required for the instructions, or to give more context. It’s possible to link to the plentymarkets manual or other external pages.

Indicate links as keywords or a number of words which appropriately cover the link’s content, but don’t indicate links as menu paths, URLs, "here", and so on.

With admonition blocks, you can highlight specific information. Use admonition blocks via Bootstrap alerts. Use info for tips and tricks and warning in case users have to take special care with certain configurations.

Warnings should always include a way to fix problems that may arise or, if the user cannot fix the problem themselves, a contact person.

Structuring your document and including navigation tools helps users find the content they need. But, beyond that it’s important that descriptions and instructions are clear and easy to understand.

Structure isn’t only important at the document level, but also when writing paragraphs and individual sentences. Each paragraph should cover only one topic. Start a new paragraph to introduce a new topic. Some paragraphs may be very short as a result, but that’s fine.

At the sentence level, use a logical sentence structure. First, describe the objective, then tell the user how to accomplish this objective. For example, explain the function of a setting first and tell the user how to carry out the setting second.

Use plain language. Plain language guidelines are designed to make texts accessible to as many readers as possible. Some basic examples include using the active voice and keeping sentences short. For a complete checklist, see the link above.
The German equivalent is the guide Die Regeln für Leichte Sprache.

Finally, take special care to be consistent in how you call certain things. This includes both elements in your UIs, such as buttons and labels, and general terminology. Pick one name and stick to it. If possible, try to be consistent with plentymarkets terminology, too. For example, use "item" instead of "article".

There are a few methods you can use to make your text sound more natural, which helps to convey your message. One of them is to use common words. If you can use common words instead of domain specific terminology, you should almost always do so. An exception is when you’re sure the user knows enough about the domain to understand the term.

Other ways of sounding natural include addressing the user directly and using contractions.

While sounding natural is important, there are some limits. For example, in speech it’s common to add adjectives and other elements as filler words, or to use parantheses to add additional information. Avoid these types of elements and constructions in writing. They can interfere with the clarity of the text.

Below, you can find an excerpt of the billiger.de user guide. This guide incorporates the principles discussed so far.