Documentation

Nebula documentation should work for everyone - any brand, all platforms. Anyone should be able to check the guidelines and understand how to use the components, regardless of their discipline.

Principles

The main goal of the documentation is to make it as easy as possible for users of the design system to acquire the information they need. With this in mind here are a few principles that will help write clear and intuitive guidelines;

• Skimmable. The documentation content should be skimmable, this helps readers identify and skip over content they already understand or is not relevant to their immediate questions. Specifically we encourage you to use headings and bulleted lists.
• Exemplary. Try to add examples for the most common use cases, but not for everything, too many examples makes the documentation less skimmable.
• Consistency. Please use the templates to help keep our documentation as consistent, and therefore as readable, as possible.

Component Documentation

This documentation is intended as a tool, designers and engineers need to be able to quickly scan them and understand how to use a component. Remember that this documentation must work for everyone across all brands and platforms. With this in mind aim for consistency and precision when writing documentation. Anything that requires further explanation should be documented elsewhere.

General Guidance

Links to other components

A mention to another component should be a Text Link, it should never open in a new window and should be kept capitalised. It can be in a singular or plural form.

Do and Don’t Lists

Use consistent imperative language, directly tell the reader to do something or not do something. We use the following key words to begin something, ideally you should always back this up with a reason for doing the action. Try to keep these as actionable as possible:

E.g.

• Always use uppercase letters
  • This helps us to main a consistent reading style
• Always use the primary brand colour
  • This helps us to keep a consistent look and feel.
• Avoid the use of custom fonts
  • It goes against our guidelines.

At the moment we are using the following keywords in our Do/Don’t Lists:

• Always - Something that should always be followed
• Never - Don’t ever do this. E.g. A different logo
• Avoid - Try your best to, but there will be circumstances where this may be necessary.
• Ensure - Things you should check.

Creating new sections

There will likely be new sections to add over time, we would like to keep these standardised at a H2 level, but feel free to add H3 sections (except inside Usage). As an example, Validation could be a new standardised section we haven’t thought about yet.