The language of Equinor and the EDS is British English. While component names in both Figma and code are written in American English, the documentation is written in British English.
Clear, accurate and concise language allows for a better user-experience of the EDS. Keep in mind that the EDS will be read by many who's first language is not English. Use words and sentences that are easy to understand and short as possible. Consistency is important, so read and use the existing EDS documentation as an example when writing new documentation.
All EDS documentation is written in Markdown.
When referring to UI in Figma, use
**bold**. Formatting should be the same as in Figma, minus any special characters.
- Layers Panel, Inspector Panel, Style Library
When referring to an individual layer in Figma, use
- Layer or Group
When referring to a frame in Figma, always use "frame/artboard" to make sure all users understand, since both terms are common.
When referring to an item being full-width, always use "full-width/full-bleed" to make sure all users understand, since both terms are common.
When referring to a component, use
When referring to keyboard shortcuts, use
When referring to a component group name, use
*italics*the first time the grouping is referenced. Following references, on the same page, do not need special formatting.
- Buttons, Top bar, Lists
Grammar and style
- Aim for a voice and tone that is natural, clear and informative.
- Use simple present tense and try to avoid words like: will, would, shall and is going to. Use future tense only when writing about something that will actually happen in the future.
- Write in active voice rather than passive. Active voice is easier to understand since it is more direct and less wordy.
- Example: Use "Click OK to save the file" instead of "The file is saved when you click OK"
- Avoid using first person point of view (we, I, our). When speaking directly to the user or customer, use second person (you, your) when needed.