mirror of
https://github.com/Alfresco/alfresco-ng2-components.git
synced 2025-07-31 17:38:48 +00:00
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
66 lines
3.4 KiB
Markdown
66 lines
3.4 KiB
Markdown
# UI text style guide in rule form
|
|
|
|
This document lists the guidelines from the
|
|
[Alfresco UI style guide](https://docs.alfresco.com/sites/docs.alfresco.com/files/public/docs_team/u2/Alfresco-Writing-Guide.pdf)
|
|
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](https://docs.alfresco.com/sites/docs.alfresco.com/files/public/docs_team/u2/Alfresco-Writing-Guide.pdf)
|
|
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. |