Documentation Writing Guide

When writing documentation for components or elements in the design system, please try to adhere to the following guidelines.

1. Focus

Keep the doc page sharply focused to reduce confusion. Try to showcase only one prop per page. However, there are exceptions, if you feel certain props must be demonstrated together, then you may showcase multiple props on a page. When needed, build pages based on specific use cases, do not blend such things with prop demos. Keep prop docs and use cases separate.

2. Don't treat docs as tests

Every good developer knows how to stress test, but this is not the place to do it. If we dump too much visuals on the page, it is going to create clutter and confuse the viewer, especially the non-tech-savvy ones such as stakeholders and designers. Remember component docs have a wide range of audience, do not heavily cater to developers. We have a tests section where we can perform tests, use that instead for any kind of stress testing.

3. Follow a defined structure

There is a page template for writing component docs. Be sure to follow its structure and fill out relevant sections.

{% include '@utils/pattern-doc-page.twig' with {
  title: title,
  description: description,
  notes: notes,
  demo: demo,
  demo_light_dark: false,
  twig_markup: twig_markup,
  html_markup: html_markup,
  js: js,
} only %}

Title

Keep the page title concise and intuitive. Use phrases not sentences.

Description

Sum up what the page is trying to demonstrate in one sentence or two. Write in plain English. Leave dev/design talk in the Notes section.

Notes

Use ordered or unordered list to create a few bullet points. These bullet points should clearly indicate requirements and gotchas of particular props being demonstrated.

Demo

Try to show the best case scenarios. We are writing documentation but we are also designing. The visual should be pleasing to the eye. So put on your wordsmith and production designer hat. Adjust the text and image to achieve the best harmony. Also, label things with this convention: "This is the [whatever]".

Twig, HTML, and JS

1. When documenting a component, Twig markup is mandatory because that's the usage we recommend for every dev. HTML markup should be provided if a component has web component markup. Otherwise leave it blank. We do not officially support HTML usage for components. Certain component docs require writing some example JS, be sure to add it to the code snippet section.
2. When documenting an element, both Twig and HTML markup are mandatory because elements are simple HTML elements with minimal classes, both usages are officially supported.

Light and Dark theme

When appropriate, show the component in both light and dark themes. Keep this to a minimum, think about if it is really necessary to show light and dark themes to get your point across before using it. Do not over complicate things.

4. Proofread

This is very important. After you are done with all the doc pages, read everything over at least once, eliminate typos and grammatical errors.

5. Catch edge cases

More often than not, you will encounter edge cases when building demos and writing docs. If you find one that breaks the component, make sure to go back to the code and fix it up.

6. Use proper elements

1. Don't use <br> for spacing.
2. Don't use <em> or <strong> for an entire sentence.
3. Write with smart quotes “, ‘, ”, ’ or use the <q> element.