Fundamental Principles

A brief overview of basic documentation principles.

Strive for consistency.

Documentation should be as consistent as possible. This enables users to apply familiar structures (e.g. the structure of explanations) to new topics in the documentation.

Write for a global audience.

A global audience does not share the same cultural background. That's why you should avoid references to things that are unique to your culture. Example:

• The Australian summer season starts in december.

This is also true for certain words or patterns in your language:

• Foo and Bar as synonyms for "example words" are likely unknown to non-native speakers and translation software.

Take a look at the Microsoft Style Guide for Global Communications to learn more.

Write for non-native speakers.

Users from all over the world will read this documentation. Most of them are not native speakers, some even use translators. Simple language should be used to make sure everyone can understand the documentation.

Write for beginners and masters alike.

Your audience contains people with all kinds of skill levels - this is true for both BetonQuest skills but also for general computer skills. Try to find common ground between these two. New users must still be able to understand your documentation while more experienced users shouldn't be bored by the same explanations over and over again.

One great way to do this is by providing optional context through links to other pages.

Write documentation about features, not code.

Users will have a hard time understanding features that are explained in technical terms. Describe what a feature does not how it works. The same is true for feature names.