Documentation style guide

General style

To keep our content clear and concise, follow these four guiding principles.

Show, don't tell

• People generally scan documentation to find what they need, and will look at an example before reading any text.
• If you can, it’s much more effective to demonstrate something visually.

Keep it simple

• Write for everyone, and consider that your audience might not be familiar with technical language.
• Favour bullet points over long sentences.

One source of truth

• Link between pieces of content rather than repeating information.
• Combine documentation for designers and developers rather than separating content.
• Use the same naming and terminology for all audiences.
• Refer to best practice documentation elsewhere on the web when guidance is not specific to using Tangram (eg. Angular docs).

Guide don’t prescribe

• Focus on the behaviour and functionality rather than how and when to use something
• Rather than saying how not to use a component, provide positive examples of uses and provide alternatives for scenarios where components may get misused.

Documentation for components

• Tangram components don’t ‘know’ about Trade Me. Write component documentation as if our components are open source and used by multiple organisations (one day they might be!).
• Avoid describing behaviour that is apparent in the component example. The exception to this is behaviour that might get missed, such as changes at smaller breakpoints.
• Avoid using code in sentences - if there’s a way to describe it in natural language, use it. Refer to components in plain language, eg. Accordion rather than tg-accordion
• Only document the current state of a component, rather than how it used to work or how it will work in the future. Don’t provide guidance on how to override components as part of the component documentation.
• Don’t refer to the Sketch design toolkit – usage guides for the design toolkit are kept in the library files.

Component examples

• Only show a single example of a component.
• When a component is made of a group of content (e.g. Tabs, Accordion, List) show three items.
• Name these using ‘first’ ‘second’ and ‘third’ e.g. ‘First heading’, ‘Second heading’ and ‘Third heading’.
• When showing icon content slots in component examples, use the ‘heart’ icon unless another icon is more obvious (eg. info ‘i’ in the info-box component)
• Avoid filling in content slots with dummy text such as Lorem ipsum, unless a lot of text is needed to indicate how the component works (eg. Scrollable container).