Global style guide
The following is a humble attempt to draw your attention to some common mistakes and misconceptions about the use of English in technical writing. Some of the points made in these guidelines may not apply to marketing texts published on the website: in general, they allow for a more relaxed approach to writing, while we tend to be inclined towards plain English.
Examples included in this tutorial are semi-fictionalized. It should be stressed that they are not intended to make fun of authors or pass judgment on someone’s writing skills, including the authors of this guide. Whatever assumptions we make about our grasp of English, there is always room for improvement. Remember: grammar is a form of magic — and there are some pretty good reasons for this!
Try being precise
As simple as it sounds, the goal of a Technical Writer is to present a story, the essentials of which are encoded into the five w’s: who, what, when, where and why.
In this, a Technical Writer isn’t much different from any writer, except may be for special attitude towards ambiguity. While trying to convey the full scope of the topic at hand, we always strive to:
use English properly
avoid ambiguity at all costs
be as short as possible
write in style
All of the following springs from these basic principles. If not, we are here to discuss!
1. Avoid placeholder phrases like note that or please note (consider using admonitions).
2. Don’t use please in the normal course of explaining how to use a product, even if you’re explaining a difficult task. Use please only when you’re asking for permission or forgiveness — for example, when what you’re asking for benefits us, inconveniences a reader or suggests a potential issue with a product.
Example:
If the issue persists, please contact your account representative.
If at all possible, don’t use in order to; instead, use to. Very occasionally, in order to does clarify meaning or make something easier to read.
3. Avoid starting all sentences with the same phrase (such as You can or To do).
4. Avoid lengthy words if shorter alternatives are available:
perform > do
utilize > use
5. Always go after shorter sentences. They are much easier to grasp.
6. Keep your paragraphs short and to the point.
Avoid pushing disconnected bits of information into a single paragraph.
Don’t hesitate to put each sentence in a separate paragraph, especially when communicating difficult concepts demanding for longer sentences.
General conventions
Here are some basic considerations.
Spelling
We stick to US English spelling.
Examples:
colour > color
initialise > initialize
cancelled > canceled
Naming
We use kebab case for naming documents, images and other files.
To avoid:
userGuide.rst
user_guide.rst
To follow:
user-guide.rst
All other naming considerations are at your discretion. Keep in mind that the filenames appear in page URLs, so you need to avoid random naming.
Tone, tense and voice
Here are some tips on how to best deliver your message to readers.
Tone
Use a proper word order
1. When telling the reader to do something, try to mention the goal of each action before you provide the instruction.
To avoid:
Click Delete if you want to delete the document.
Select Header Row on the Design tab.
See [a link] for more information.
To follow: - To delete the document, click Delete. - On the Design tab, select Header Row. - For more information, see [a link].
To learn more, see an entry on clause order in Google style guide.
2. When giving instructions, avoid using must and have to. Whenever you need to urge a user to do something, use should or need to.
To avoid:
You must enter your password.
To follow:
Enter your password.
It is OK to use must when referring to technical issues or abstract entities:
The password must contain at least eight characters.
3. Use may with caution. In general, this word is reserved for official policy or legal considerations. To convey possibility, use can or might instead. To convey permission, use can instead.
4. In most cases, capability wins over opportunity and possibility big time. More often yet, you can go with allows or enables instead.
To avoid:
Risk monitor provides you with an opportunity to monitor risks for customers’ assets.
With this release, we have provided a possibility to sort tables by any field.
To follow:
The risk monitor allows you to monitor risks posed to customer assets.
With this release, we have provided the capability to sort tables by any field.
5. Abbreviate simple sequences by using right angle brackets. Include a space before and after each bracket, and don’t make the brackets bold.
Example:
Select Accounts > Other accounts > Add an account.
To learn more, see an entry on procedures in Google style guide.
Avoid parenthetical words
Do not begin sentences with Now, Also or Then.
To avoid:
Also, you can customize user options.
Now, click OK.
Then, the Add new file menu is displayed.
Most often, you can find better alternatives to these words or avoid them altogether.
To follow:
In addition, you can customize user options.
Next, click OK.
After clicking the Add image button, the Add new image window is displayed.
Use helper words
Helper words such as then and that are frequently left out of conversational English. Use these words to avoid ambiguity.
Examples:
If the attribute key is not found, then the default value is returned.
Navigate to Commissions > Users, and then click New.
Avoid unwarranted assumptions about the readers
1. Avoid using simple/simply and easy/easily (as in simply enable this option or as simple as that). Things may not be that simple from a user’s perspective, and there is no reason for making sentences longer.
Avoid just and of course as well (as in just click this button).
2. Use appears to instead of seems to. The latter implies there is a cognitive bias on the reader’s part, while the former suggests something indeed could be wrong with the issue the reader is facing.
To avoid:
If everything seems to be correct, contact the administrator to check the status of your profile.
To follow:
If everything appears to be correct, contact the administrator to check the status of your profile.
Tense
Try to avoid future tense in general. Most often, it doesn’t convey any additional information and there is no need to complicate sentences in this way.
To avoid:
After clicking this button, a new window will be displayed.
To follow:
After clicking this button, a new window is displayed.
Don’t overuse Present Perfect, as it rarely adds clarity to sentences that are already enough complicated as they are. Try using Present Simple as a more straightforward option:
To avoid:
The open positions on PAMM investment accounts have been closed, and a position in the same volume has been closed on the PAMM master account.
To follow:
The open positions on PAMM investment accounts are closed, while a position in the same volume is closed on the PAMM master account.
Voice
Avoid passive voice whenever you can.
To avoid:
Wallet settings are accessible from the wallet list by clicking the wallet ID or the Settings button.
To follow:
To access wallet settings from the wallet list, click the wallet ID or the Settings button.
In most cases, the active voice is preferred, unless it would sound unnatural or look out of place.
Remember: there are no rules against using the passive voice as such, this is only a question of clarity and common sense.
Taking time to review your text
Here is a great article on this subject: Final publishing review.
Articles
Use articles generously.
When in doubt, stick to the one you find most appropriate instead of avoiding an article altogether.
To avoid:
Default value is
0.Specify user name and click OK button.
To follow:
The default value is
0.Specify the username and click the OK button.
Be aware of mass nouns (also called uncountable nouns), such as information or data. You can find a good case for this on the Grammar Girl website.
Admittedly, articles may be tricky. Feel free to ask your fellow Technical Writers: as always, we are here to help and discuss.
There is nothing wrong with avoiding articles in API names, UI captions or descriptions to GitLab commits. However, we should stick to the natural language in most other cases: for example, when describing the API and providing tooltips to UI elements.
Nouns
General conventions
1. Spell email without hyphen:
e-mail > email
2. Spell cryptocurrency as a single word (but not crypto exchange).
3. Don’t use rights in the sense of permissions.
Plural forms of Latin nouns
Apart from Latin acronyms, try to limit the use of Latin nouns in general. Here are some of our conventions regarding their spelling:
analysis — use only in singular, avoid the plural form
bonus / bonuses
criterion / criteria — the plural form is more common, avoid the singular
data — we always spell it in plural, but refer to it as a singular noun (such as this data)
index / indexes
status / statuses
Pronouns
Here are some quick and dirty tips on the proper use of pronouns.
Gender-neutral pronouns
Don’t use gender-specific pronouns unless the person you’re referring to is actually that gender.
In particular, don’t use he, him, his, she or her as gender-neutral pronouns, and don’t use he/she or (s)he or other such punctuational approaches. Instead, use the singular they.
To avoid:
If a user is granted admin permissions, she can customize her account settings.
To follow:
If users are granted admin permissions, they can customize their account settings.
If a user is granted admin permissions, they can customize their account settings.
It helps to remember that singular they has been in use for a long time. For example, Jane Austen used it, and in 2015 the Washington Post adopted it as part of their official style.
For more suggestions, see The Chicago Manual of Style, 16th edition, section 5.225, “Nine techniques for achieving gender neutrality”.
Verbs
Pay attention to which verbs you choose and how you use them.
To avoid:
You can give special permissions to certain users.
To follow:
You can grant certain users special permissions.
Don’t use a verb unless you are confident as to its governing nouns and proper prepositions. For example:
Don’t add on when speaking of clicking or tapping UI elements.
To avoid:
Click on a row to view detailed information.
To follow:
Click a row to view detailed information.
Be aware of the correct use of prepositions with the verb assign.
Wrong:
A user can be assigned with various roles.
Various roles can be assigned a user.
Correct:
A user can be assigned various roles.
Various roles can be assigned to a user.
Get comfortable with the verbs allow and enable.
Wrong:
This option allows you create new accounts.
Correct:
This option allows you to create new accounts.
This option allows creating new accounts.
This option enables you to create new accounts.
Best:
Use this option to create new accounts.
Using this option, you can create new accounts.
Use a bare infinitive (without to) after the verb help.
Correct:
This helps you type faster.
With certain nouns, specific verbs might be required or preferred.
Wrong:
Perform these commands in the terminal.
Correct:
Execute these commands in the terminal.
Run these commands in the terminal.
Some verbs may just win over other verbs in a given context.
Clumsier:
The correct answer is output.
Straight:
The correct answer is returned.
The correct answer is displayed.
In general, verbs are preferred over nominalization:
completion > complete
provision > provide
usage > use
For a brief analysis of such cases, see the rubric “Avoid nominalisations” in the plain English guide.
Be careful with how you use the verb recommend:
Wrong:
It is recommended to take the red pill.
The red pill is recommended.
Correct:
The recommended approach is to take the red pill.
We recommend that you take the red pill.
We recommend taking the red pill.
We recommend against taking the blue pill.
The verb sign in is generally better than log in. However, if you’re documenting a tool that uses the term log in, then use the term that the tool uses.
Prepositions
1. Use in with menu and list:
in the menu, in the list
Use on with tab and screen:
on the tab, on the screen
To learn more, see an entry on prepositions in Google style guide.
2. With information, consider using about as a less ambiguous alternative to on, such as when using cross-references:
To avoid:
You can view information on user groups on this page.
To follow:
You can view information about user groups on this page.
Still, you may prefer to use on in some contexts, such as before how to, although there is no rule against using about instead:
For information on how to manage user groups, see [a link].
3. Be careful when using with. Sometimes, it is hard to tell to which part of a sentence this word applies. In most cases, you can do without it.
To avoid:
This code is sent to the admin email with each login attempt.
The detailed information is a separate page with user data.
To follow:
This code is sent to the admin email upon each login attempt.
The detailed information is presented on a separate page containing the user data.
Conjunctions
Keep in mind the subtleties of whether (or not). Often or not is redundant after whether, such as in the following cases:
She wonders whether the teacher will attend.
The teacher will base his decision on whether the car has been repaired.
Whether the car will be ready depends on the mechanic.
Put more briefly, whether can generally stand alone when its clause is functioning as a noun, but not when the clause is serving as an adverb.
With that in mind, or not is necessary when the phrase whether or not means regardless of whether:
Whether or not you like it, I’m going out tonight.
To learn more, see an entry on this in Google style guide.
Adjectives
Feel free to add more tips on adjectives if you find it useful.
That / which
The standard rule of grammar goes as follows:
The usage of that versus which depends upon whether the following clause is restrictive or non-restrictive.
That is used to indicate a specific object, item, person, condition and so on, while which is used to add supporting or parenthetical information about objects, items, people and situations.
Because which indicates a non-restrictive (optional) clause, it is usually set off by commas before which and at the end of the clause.
However, not everyone are eager to follow this “rule” and there is a great deal of disagreement among writers and grammarians as to whether this rule holds in practice.
Since we are barely in a position to decide upon proper use of that versus which, you are free to use them as you see fit.
Possessives
Try to avoid repeating of in possessive constructions. Whenever you can drop of altogether without introducing ambiguity, go for it.
To avoid:
The content of the pages of the Admin Panel is organized in tables.
The owner invites other members of the team.
Owner of the wallet cannot be changed.
To follow:
The content of the Admin Panel pages is displayed in tables.
The owner invites other team members.
The wallet owner cannot be changed.
You can also try to break down constructions overloaded with of into separate sentences.
Try to avoid plural forms in possessive case.
To avoid:
Users’ accounts
Users accounts
To follow:
User accounts
Punctuation
General points:
Keep in mind the difference between comma use in English and Russian.
Use punctuation to help readers separate parts of a sentence.
1. When you need to use dash, always use the em-dash (—).
2. Don’t use the Oxford (serial) comma before and/or.
Example:
You can view the order list, edit order settings or place new orders.
However, cases of helper words might constitute an exception to this convention.
3. Place periods and commas after closing quotation marks, not before them.
Example:
They say “this is the way to go”.
4. There are no rules as to “curly” or “straight” quotes and apostrophes (such as in don’t and don’t). The only rule is to be consistent with those you use across the projects at hand.
5. If you need an ellipsis, here is one: …
6. Consider choosing a period over excessive colons, semicolons, dashes and parentheses.
They are good for introducing examples:
You can grant access to your wallets to other persons: for example, to your team members or company employees.
You can grant access to your wallets to other persons (for example, to your team members or company employees).
You can grant access to your wallets to other persons; for example, to your team members or company employees.
You can grant access to your wallets to other persons. For example, to your team members or company employees.
They are also good for lists.
7. Place commas after adverbial modifiers (such as of time and place).
Examples:
On the main menu, navigate to Settings.
While the report is being generated, a progress bar is displayed.
For hashing, the HMAC-SHA512 algorithm is used.
Headings / Titles
1. We use title case only for H1 headings (document titles):
The Quick Brown Fox Jumps Over the Lazy Dog
For all other headings, use sentence case:
The quick brown fox jumps over the lazy dog
2. Don’t put a period at the end of a title.
3. Use articles for all headers and titles.
4. For a task-based heading, start with a bare infinitive, also known as a plain form or base form verb. In English, the imperative mood also uses the base form verb, so it looks the same as the bare infinitive.
To avoid:
Creating an account
To follow:
Create an account
5. Use parallel syntax for titles at each nesting level. Before submitting your document for review, take time to read all titles aloud to ensure that they are consistent.
To avoid:
Create account
User options
Using extensions
To follow:
Create an account
Customize user options
Use extensions
Lists and tables
1. Always precede a list or a table with an introductory sentence. The sentence can end with a colon or a period:
usually a colon if it immediately precedes the list or table
usually a period if there is more material (such as a note paragraph) between the introduction and the table
Always introduce a table with a complete sentence.
To avoid:
The fields are:
To follow:
The fields are defined as follows:
The following table illustrates the available options.
2. Put a period at the end of list and table items if they amount to complete sentences or invite multiple sentences.
Don’t put a period or semicolon at the end of list and table items if they are plain short or comprised from incomplete sentences.
For example:
Select one of the following values:
0.5
1.5
100
Using this option you can:
manage user accounts
place new orders
perform other tasks
As always, think to avoid verbiage. Thinking to avoid periods helps produce shorter lists. Parentheses may come handy, such as in this case:
Other fees may include:
tier fees based on pre-defined volumes traded by users (across selected markets within a 30-day period)
market fees defined individually for each market (by default, these fees are charged for all trades on the market unless other fees apply)
3. Use parallel syntax for list and table items.
To avoid:
To get access to GitLab, you need:
to set up VPN
access permissions to https://vcsdocs.b2broker.tech/
To follow:
To get access to GitLab, you need:
a set-up VPN
access permissions to https://vcsdocs.b2broker.tech/
To get access to GitLab, you need to:
set up VPN
obtain access permissions to https://vcsdocs.b2broker.tech/
4. Any list item can contain more than one paragraph. Try to keep them at two for each item.
To learn more, see an entry on lists in Google style guide.
References
When adding cross-references, avoid repeating the information conveyed by a link title:
To avoid:
To learn about managing users, refer to [Manage users].
For information on how to create user lists, see [Create user lists].
To follow:
To learn more, refer to [Managing users].
For more information, see [Create user lists].
Contractions
Avoid ambiguous or awkward contractions, such as there’d, it’ll, and they’d.
However, it’s fine to use -n’t contractions, such as isn’t, don’t and can’t. One reason for this is that it’s sometimes easy for a reader to miss the word not, whereas it’s harder to misread don’t as do.
Whether you use contractions or not, be consistent with it across the entire document you are working at. For example, don’t use can’t and cannot in the same text.
Never form a contraction from a noun and a verb, such as Our company’s developing a lot of new cloud services.
To learn more, see:
Acronyms and abbreviations
Avoid Latin abbreviations i.e., e.g., etc.
Use their English equivalents instead:
i.e. — that is, namely, in particular
e.g. — for example, such as
etc. — and so on
To learn more, see an entry on abbreviations in Google style guide.
Numbers
Use period, not comma, as a decimal separator:
Set this value to 0.3.
Use comma as a numeric separator:
Set this value to 25,000,000.
No separator is used in the decimal part, regardless of how long it is:
Set this value to 0.0000000002 BTC.
In body text, spell out whole numbers from zero through nine, and use numerals for 10 or greater. It’s OK to use numerals for zero through nine when you have limited space, such as in tables and UI.
Other tips and conventions
1. Use also with caution: it is a tricky word prone to introducing ambiguity.
To avoid:
The owner also receives API keys to email after registration.
To follow:
In addition, the owner receives API keys by email upon registration.
2. The word several implies few, not too many. Consider multiple or various as alternatives suggesting plentitude and availability.
To avoid:
Each group can contain several items.
On this page, you can configure several options.
To follow:
Each group can contain multiple items.
On this page, you can configure various options.
3. In most cases, you don’t really want to use complex as an adjective.
To avoid:
This is a complex tool that allows you to solve a variety of tasks.
Performing risk analysis properly is a complex task.
To follow:
This is a sophisticated tool that allows you to solve a variety of tasks.
Performing risk analysis properly is not a trivial task.
4. Don’t use vice-versa. Instead, use a phrase like the other way around, conversely or otherwise.
In some contexts, vice versa is unclear or imprecise because in a complex sentence it’s hard to know which two things are swapped with each other. In such cases, make it explicitly clear what two things are swapped.
5. Avoid thus: use therefore or some other option instead.
6. Spell filename extensions in uppercase and without a period (PDF, XLSX).
Text formatting
Here are some tips on using various text formatting options.
Bold
We use bold when referring to interface elements, as well as sections and subsections in the UI:
Click OK to proceed.
Navigate to Clients > General in the main menu.
You can also use bold to add emphasis to various parts of text. For example, you might want to highlight product names and specific features:
PrimeXM provides a web user interface…
Trading API is intended for…
Use bold cautiously as to not overload the text and make it harder to comprehend.
Monospace
We use monospace for:
names and values of fields and parameters:
This field is required only if
isStopistrue.structure names:
The request includes the
dataJSON-structure.method names, endpoints and HTTP verbs:
The base endpoint for requests is
[base].The
POSTandDELETErequests must include this data.
Italic
Use italics when you need to draw attention to a particular word or phrase in the prose of your documentation, such as when introducing a key concept or new word, or when discussing a particular word.
Since text in italics is generally harder to read, avoid adding it to long parts of the text. To put an emphasis on an entire sentence, consider using admonitions instead.
Writing for UI
Error messages
Place to start: MS guidelines on error messages
Useful guide: Error Messages in Windows 7.
Useful guide: Warning Messages in Windows 7
Useful resources
Consult the following resources for more tips:
And what comes to grammar… Be skeptical of any grammarian you meet at noon. In here this order:
William Strunk (the “Elements of Style”)
Add yours below:
#onboarding #rules