Documentation writing style

There are a couple of things worth being aware of, if you decide to contribute additional documentation to the project. These things are related to the writing style and the tone of voice and should make it easy for readers to understand the content and also be able to identify with the information written.

🚨 Are you contributing? No worries, if you don't get all the rules right from the start we'll help you out making your docs compliant to these guidelines!

Written text

The text in the AXA Web Toolkit should describe the components, utilities and plugins of the project. It should also mention best practices and recommendations.

Do

• Do start every page with a lead (<p class="lead">) text which summarizes the aims of the document.
• Do keep your sentences short and avoid any complicated statements.

Do not

• Do not use «we» to talk about the contributors. (ex. We've decided to do things like this.) A separation between the consumers of the AXA Web Toolkit and the contributors is highly undesirable.
• Copy whole tutorials or guidelines from the internet. Rather link to them.

Code snippets

Code snippets are an essential part of the docs.
They might in some cases be the only thing that people read.

Do

• Do keep the code snippets short. Remove all unnecessary redundancies (ex. show two items in a list in order to show the default and active states, but remove all additional items).