Documenting a new component or foundation

Scope and audience

This guide explains how to write documentation for the design system website.

Documentation should meet the needs of interaction designers, content designers, and developers. It should be easy to understand so anyone making products for Parliament can use your component correctly.

Documentation template

We have created a template which outlines the typical information you should include in your documentation.

You must also include specific accessibility or content guidance where relevant. For example, known accessibility issues, or specific error message guidance.

If you work in Parliament, contact us on the #design-system Slack channel to request the template.

Writing best practice

Format headings correctly

In the template we have included the formatting heading styles to apply to the sections.

If you use other headings make sure to apply the correct style in the correct hierarchy.

Address your user in your writing style

Use ‘we’ when referring to UK Parliament. Use ‘you’ and ‘your’ when addressing users of the design system.

When talking about users of our products, use the plural. For example, ‘tabs hide content from users and not everyone will understand how they work’.

Provide clear instructions

If someone must do something, make it clear. Words like ‘should’ or ‘could’ add an element of doubt. If something is needed, use ‘must’. You can also use ‘do not’ and ‘never’.

Use consistent style and terminology

Use the digital content style guide for style, spelling, and punctuation rules. This includes what words to capitalise and how to format lead in sentences and bullet points.