Helsinki Design System
Helsinki Design System
Getting started
Guidelines
Visual assets
Design tokens
Components
Patterns
About
Contributing
Resources

Contributing to Documentation

Documentation is an essential part of HDS. In addition to component specific documentation, HDS provides broader guidelines, instructionsand patterns for creating City of Helsinki digital services.

When contributing for documentation, there are a couple of ways of doing it

Editing pages directly in GitHub website

The easiest way to edit a page is with the Edit this page on Github link that appears at the bottom of every page on the site. The link opens the specific Github page where you can edit the content and propose the change with a pull request.

Forking repository and setting up 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 every one at the City of Helsinki organisation 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 developer 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.