Docs style guide for contributing
Last updated
Was this helpful?
Last updated
Was this helpful?
In order to keep the documentation in this repository consistent and accessible, refer to the style guidelines below before contributing documentation.
All documentation is written in English, using American spelling. Refer to for an overview of differences between American and British spelling.
All documentation is written in a formal writing voice. For example, avoid the use of contractions or colloquial language. Please refer to for a complete set of instructions and examples.
Correct: Do not attempt to solve the problem without consulting the support lead.
Incorrect: Don't try to fix it without hitting up the support lead.
General descriptions are written in the passive voice (as opposed to the active voice).
Correct: Design tokens are used for customizing the application theme.
Incorrect: You can use design tokens to customize your application theme.
Instructions are written in the passive voice or in the second person.
Correct: This module is then imported.
Correct: You then import this module.
Incorrect: We then import this module.
The first time an abbreviation is used on a page, the fully written meaning should be included.
For example: it is recommended to use Node Version Manager (NVM)
If possible, a release note should link to the documentation page of the related feature. For each release note, try to give an example of its use case, and only go into technical detail when necessary.
Release notes for new features should convey clearly what functionality has been introduced, and how this functionality can be used.
Any required steps to use new functionality either go in the migration section if it is a one time action, or should be listed on a separate page describing the feature so that people can find the usage in later versions.
Every page under the sections 'Introduction', 'Using Valtimo', and 'Extending Valtimo' should contain an introductory paragraph at the top of the page. Try to mention use cases in this introduction. Under other sections, assess on a case-by-case basis whether a page should contain an introduction.
Adding screenshots is useful when writing instructions. All text contained in the screenshot should be in English. Preferably show screenshots from the default Valtimo implementation, and remember to keep all screenshots up-to-date.
When including a reference to an external source, a link to the external documentation should be included when possible.
When contributing documentation under a certain section, be mindful of its target audience.