This page features the style guide that’s applicable across all our products. Use the right side of the page to annotate or refine the guide to fit the specifics of your product.
Headings
Never use Heading 1 on the page.
Use Heading 2 and Heading 3 regularly. Heading 4 only when necessary - it can be easily substituted by a text in bold.
Page headings: Sentence case
Page titles: All Caps of All Fonts
General advice
Use YOU
Speak directly to the reader and treat them as someone who will be following your instructions.
No ‘users will’ or ‘customer should’.
Of course, there may be cases when you need to refer to you user’s users. In that case, follow the pattern: Your users will… Ensure that your customers….
Be direct.
Use:
-
Click this
-
Download that
-
We recommend that you do
Do not use:
-
please
-
if you wish
-
consider doing
Formatting and links
To emphasize the word, use bold.
When creating a link to another page, use the following format:
To learn more, see https://emplifi-docs.atlassian.net/wiki/spaces/DP/pages/9409823.
Use the ‘inline’ type of link.
Ensure that the linked text and the title of the page are identical. As above. That ensures that when you change the page title, the linked text changes too. The to learn, see format ensures that the grammar would be always correct.
This is extremely important for space sync apps to convert links from the source space to the target space.
Full stops / periods
A sentence starts with a capital leter and ends with a full stop/period. Even in lists. If the item on the list is a phrase or a word, lowercase and no full stop. See the following sections for details.
Use number lists
Use number lists for processes/procedures longer than two steps (or with two if it helps to declutter the content).
-
Use bold to denote the actual clickable element. Click Add dashboard.
-
Click the Blank dashboard tile.
-
Click Add widget.
The list of widgets displays.
Unknown Attachment
-
Select the widget that you want to use.
The widget’s configuration page appears. -
Configure the widget.
Example:Unknown Attachment
Configuration options for individual widgets differ. In general, you can define the following parameters:
-
chart type
-
widget name
-
data source
-
filters
-
breakdown options
-
widget specific options
-
-
Click Create widget.
The widget appears on your dashboard.
For more information, see Better Code test .
Use bullet lists
Use bullet lists (unordered lists) when the order of the items on the list does not have to follow a sequence.
Images and screenshots
Always create screenshots from a retina screen (all MacBooks) or a scaled Windows screen.
No frames are needed. Viewport, that generates our doc pages, does that for us.
In normal paragraphs, indent images to the left - if the image is (should be) large to fill in the entire column, feel free to keep it centered.
In lists, images are automatically indented left.
Unknown Attachment
Sizing
There’s no one-size-fits-all policy - use common sense to determine the size. Look at the information value of the image.
-
If the text content important - you may want it to be readable and use a larger image. Just make sure that, when taking the screenshot, you make it possible 😉.
-
Fs the image used only to point to a location of the item in the UI - it’s OK to use a smaller-size image. The clickable item will be highlighted in the text and it’s just the location that’s important.
Snagit
Guidelines and styles for screenshots will follow.
When sizing fonts and frames… default numbers are a general guideline. Size is relative and should make sense (hold information value) in the context of the specific screenshot’s size and resolution.
Example: A 2px outline of an item in the UI will look differently on a full window screenshot and on a drop-down menu screenshot.
Tables
Tables are pretty straightforward.
|
Header row |
Header row |
Header row |
|---|---|---|
|
cell |
cell |
cell |
|
|
|
|
Unless absolutely necessary, avoid tables with two columns.
Instead, use the following term - definition formatting:
-
Yellow - enter soft return (shift+Enter)
Color of lemons -
Green
Color of grass -
Blue
Color of depression
Headings
You can use Heading 4 but ensure that you limit TOC to heading 3.
General advice
Wherever possible, use the the role/position.
Example:
-
As an admin, you will…
-
Ensure that your admins configure general user access…
Be as specific as you can be.