Contributing to the documentation
Documentation is an essential part of HDS. In addition to component-specific documentation, HDS provides broader guidelines, instructions, and patterns for creating City of Helsinki digital services.
When contributing to documentation, there are a couple of ways of doing it.
Editing pages directly on the GitHub
The easiest way to edit a page is with the Edit this page on Github link that appears at the bottom of every page. The link opens the specific Github page to edit the content and propose a change with a pull request.
Forking repository and setting up a local environment
If you are planning regular or more comprehensive content updates, you will want to fork the repository and install some of the tools we use to build the website. This will create an easier workflow for you long term. Follow README in documentation site package to get you started setting up local development environment.
General guidelines for writing documentation
- HDS documentation is written in British English.
- The audience of the documentation includes everyone at the City of Helsinki with the main focus on developers, designers, and product owners. Try to avoid technical jargon to keep documentation understandable for everyone.
- HDS documentation aims to guide designers and developers and not restrict them. Most of the time the last word is left to the user of the design system. Keep this in mind - especially when writing component and token principles.
- Documentation in Components and Design tokens sections always should have their counterpart both in design kit and implementation. HDS aims not to release documentation before implementation is released.
- Documentation site styles take care of most of the accessibility issues. You mostly need to ensure that heading levels are used semantically (refer to HDS typography documentation) and external links are correctly visualized (you can use the HDS provided Link component.