dfc83489e2
* [ADF-3093] Started li18nt VS Code extension * [ADF-3093] Started work on UI style lint tool for VSCode * [ADF-3093] Added UI style rules up to sg0006 * [ADF-3093] Added remaining style rules * [ADF-3093] Added docs and command line tool * [ADF-3093] Removed Microsoft notices and updated licences to Apache-2.0
3.4 KiB
UI text style guide in rule form
This document lists the guidelines from the Alfresco UI style guide in the form of separate rules. The list can be as a check to identify specific types of mistake and suggest solutions. However, the main style guide remains the definitive source for the guidelines and explains and develops the reasons for style choices in greater depth.
Rules
SG0001: Avoid polite words ("please", "thank you")
People tend to find direct commands ("do this", "go here") rude in everyday conversation but, in UI text, the meaning is very different. Saying "use xxx to solve problem yyy" reads as a recommendation ("if you think you have problem yyy then using xxx is a good way to solve it"). Using expressions like "please", "thank you", and "feel free" takes up space and makes the text less direct and easy to read.
SG0002: Avoid interjections ("oops", "wow", "yeah")
It is quite common for UI text in other products to include words like this to add a bit of fun to the UI. However, it is Alfresco's style to avoid these words to keep the UI more "serious" and professional.
SG0003: Avoid exclamations ("!")
Exclamations generally look as though they are supposed to be funny or angry. This doesn't fit in well with Alfresco's professional UI style.
SG0004: Avoid unusual punctuation (";", "~", "^")
These punctuation marks are valid in English but their meaning is often subtle and they are rarely used. The text is generally clearer without them, especially for a user who isn't a native English speaker.
SG0005: Don't use the ampersand ("&") as a replacement for "and"
The ampersand ("&") character is common in signs and captions but isn't normally used in messages and body text. Use the word "and" in full.
SG0006: Write numbers using digits instead of words
Numbers take up a lot more screen space when they are written out as words ("one hundred and twenty three") rather than digits ("123"). Style guides differ on this issue but Alfresco's style is to prefer digits over words when writing numbers. The exception is for numbers from 1 million upwards. For these, write digits followed by "million", "billion", etc. Something like "10 billion" is easier to read than 10000000000.
SG0007: Contractions ("can't", "won't" "isn't") are usually better than the equivalent phrase
Contractions such as "can't", "won't" and "isn't" are shorter and more familiar than "cannot", "will not", "is not" and help to make the UI seem a bit friendlier. Avoid the full phrase except in cases where you want to emphasise an instruction very strongly ("Do not change these settings unless you are sure you need to do so").
SG0008: Leave out trademark and copyright symbols
There is no legal requirement to use trademark and copyright symbols ("™", "©", "®") in UI text. They will be covered in the docs if they are needed at all, so don't use them in the UI.
SG0009: Avoid abbreviations for common phrases ("etc", "e.g.")
Abbreviations that represent English phrases ("i.e.", "etc") tend to read awkwardly and so they should be avoided in UI text. The exception is OK, which is widely used. However, abbreviations and acronyms for well-known products and terms (ADF, SDK) are fine.