Documentation
The Valtimo product team aims to deliver new functionality to its users quickly. Contributions from outside the core development team are very much appreciated and welcomed. Part of making a contribution to Valtimo is writing clear and accessible documentation.
Writing documentation
There are two different circumstances for which documentation for Valtimo can be written.
Either because it is related to a particular change in the product that will be included in an upcoming release.
Or to add something that is not related to an upcoming release, e.g. fixing spelling errors or documenting part of an already existing feature.
Documentation related to an upcoming release
Write documentation/release notes. These should be written as a PR for this repository.
Information on what language to use, as well as general guidelines can be found here.
Release notes to in the
release-notes
package.If new pages are added, these should also be added to
SUMMARY.md
. The sidebar shown on GitBook corresponds to this structure.It is required to fork the repository to implement the changes and create the PR.
The Valtimo team will merge the PR after approval.
Documentation unrelated to an upcoming release
In case of a new page, discuss the documentation you want to write with someone from the Valtimo team.
Write documentation. This should be written as a PR for this repository. Make a branch from the
main
branch, add all team Valtimo developers to this PR as reviewers.Merge the branch after getting an approval from the Valtimo team.
Style guide
In order to keep the documentation in this repository consistent and accessible, refer to the style guidelines below before contributing to the documentation.
Spelling
All documentation is written in English, using American spelling. Refer to this page for an overview of differences between American and British spelling.
Formal writing voice
All documentation is written in a formal writing voice. For example, avoid the use of contractions or colloquial language. Please refer to this page 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
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
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.
Abbreviations
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)
Last updated