Writing Style

This writing style guide is intended for those who write customer-facing content for M-Files and other related products. It provides stylistic and grammatical guidelines as well as punctuation ground rules for writing clear and consistent user documentation. The style guide also includes specific guidelines for creating user interface texts. These guidelines should be followed by everyone concerned to ensure that all content is written in the same, clear, and concise manner.

Conciseness and Consistency

• Stay concise. Consider what the user absolutely needs to know and leave out any non-essential details.
  • If the issue or topic is especially complex, instruct the user to see supplemental material.

• Stay consistent. Always use the same terms for the same elements. This makes it a lot easier for the users to find their way around the user interface.

Tone and Voice of User Interface Texts

This section applies to user interface texts only.

• Keep the texts casual, polite, and friendly.
  • Use sorry and please if it feels natural to do so.
  • Feel free to use contractions like don’t, shouldn’t, we’re, and so on.
  • Do not, however, use abbreviations such as etc., e.g., and i.e.

• If you have to choose, be easily understandable rather than colorful and exciting. In most cases, however, being clear does not automatically mean that you need to also sound flat and uninteresting.

Style Conventions

This section outlines the style conventions used at M-Files.

Standard American English

All M-Files content must be written in Standard American English. The most significant difference between written Standard American English and, for example, written British English is that certain words are spelled differently. Pay special attention to how you spell certain words.

The tables below list spelling differences of words and suffixes (word endings) between Standard American English and British English. Lists are not exhaustive, but they cover some of the most common differences. Whenever you are unsure of how a word is spelled in Standard American English, consult a dictionary, such as the online dictionaries by Merriam-Webster or Macmillan.

Words with Specific Endings

Verb Inflection Differences

Spelling Differences

Readability

Avoid large chunks of text. Too much text in the user interface looks scary and lowers the chance of the user actually reading it. In documentation, the maximum number of words in a sentence is:

• 20 in procedures

  In M-Files Admin, go to the "Advanced Vault Settings" section.

• 25 in descriptive writing

  You can control the workflow of the object and do a workflow state transition with the workflow-related fields at the bottom of the metadata card.

Capitalization

Capitalization means writing a word with the first letter as an upper-case letter and the rest of the word in lower case. This section sets the ground rules for using capitalization in M-Files content.

Headings

Headings should use the so-called title case, in which the first letter of each major word in the heading is capitalized, including individual words in hyphenated word combinations (such as Client-Side Registry Settings). Articles (a/an/the), conjunctions, and prepositions with fewer than five letters are not capitalized unless they start the heading. Examples of conjunctions not to be capitalized are and, but, and if. Examples of prepositions not to be capitalized are at, to, for, and with.

In contrast to the title case is the sentence case, which is the standard way of capitalizing English sentences. In the sentence case, only the first letter of a sentence is capitalized and subsequent letters are in lowercase, with the exception of proper names and acronyms.

Here are some examples of the title case:

Using Federated Authentication with M-Files

Comparison Between Esperanto and Ido

A Handy Guide to Cycling Routes in Tampere

Proper Names

Proper names are nouns denoting unique entities. Proper names are always capitalized and are thus orthographically distinguished from other parts of speech in sentence case. Proper names include product names (such as M-Files), organization names (such as Microsoft), place names (such as Tampere), persons (such as Jacques Anquetil) or any other names of individual entities.

Acronyms

Acronyms are abbreviations formed from the initial letters or parts in a phrase or a word. Examples of acronyms include URL, _laser, HDMI, tRNA, and PnP. Acronyms are written in all uppercase, mixed case or lowercase, but most commonly follow the all-uppercase capitalization scheme, in which every letter in the acronym is capitalized (such as in HDMI and URL).

Some acronyms use mixed-case capitalization, especially the ones that are derived from an existing acronym by affixing. tRNA, for instance, uses a mixed-case capitalization scheme, since it is formed by affixing “transfer” to the acronym RNA. PnP similarly uses mixed-case capitalization, since the letter “n” in the acronym stands for “and”, which is commonly written in lowercase even in title case.

If the sentence begins with an acronym that starts with a lowercase letter, do not capitalize the first letter.

Some commonly used acronyms have taken on an identity as regular words. Such acronyms are therefore written in all lowercase letter. Examples of such acronyms include laser and scuba.

Do not use apostrophes (‘) when forming plural forms of acronyms. For example, write URLs, not URL’s.

Classic M-Files Desktop, Classic M-Files Web, and M-Files Admin

Use title case for the following elements:

• Dialog and tab titles

• Menu items

• Button labels

• Node names in navigation hierarchys

Use sentence case for the following elements:

• Check box and radio button options

• Drop-down list options

• Group box labels

• Value and setting labels

• Dialog body text

M-Files Mobile for iOS

Use title case for message titles, button names, and menu items. Use sentence case for message content. When in doubt, use title case.

M-Files Manage, M-Files Web, and All Other New User Interfaces

Use sentence case throughout the user interface.

Punctuation

This section provides ground rules for the proper use of punctuation. These guidelines consist of agreed-upon conventions of specific cases where variation in the use of punctuation may occur.

Colons

In addition to using colons (:) normally in any body text content, add a colon after the following elements:

• Labels calling for the user’s attention like Note or Important
• Value and setting labels in various dialogs like in the example below

Commas and Semicolons

Rules for using commas (,) and semicolons (;):

• Use a comma to separate three or more words, phrases, or clauses in a series. Comma must also be used before the final conjunction (and, or, or nor) in a series of three or more elements:

  You can find the corresponding M-Files functions in PowerPoint versions 2003, 2007, 2010, and 2013.

• Use a comma to separate an introductory phrase from the rest of the sentence:

  In M-Files, you can create multi-file or single-file documents.

• Use a comma before a conjunction that links two independent clauses:

  The server was specified in the previous field, and in this field, you specify the connection port.

• Do not use a comma before the word that. This is today considered nonstandard in English.
• If the items in a list are long, complex, or contain conjunctions or commas, use a semicolon (;) to separate such items if absolutely necessary.

Question Marks

Place a question mark (?) at the end of any question. This also applies to the user interface.

Quotation Marks

Quotation marks are used for identifying named entities, such as object or command names, in text content. Always use double quotes (“) when quoting something. Use single quotes (‘) only if you need to use quotation marks inside double quotes.

Use double quotes to refer to user interface elements in cases where you cannot italicize or bold the text referring to the element. Referring to user interface elements in headings, for example, can be one such case.

In the user interface, use both quotation marks and apostrophes sparingly. For example, referring to short command names does not usually require using quotation marks: Use the Refresh Now command to resynchronize the group members.

Dashes

There are two types of dashes to be used in documentation:

• En dash
• Hyphen

You can create an en dash (–) by typing ALT+0150 in Windows or by typing a single hyphen between two words in Word with AutoFormat enabled. The en dash is commonly used for indicating a closed range of values. Follow these guidelines for using en dashes:

• Use an en dash with no whitespace around the dash to indicate a range. Alternatively, you can use constructions such as from … to for indicating a range:

  Repeat the steps 1–4 separately for each subtask.

  Repeat the steps from 1 to 4 separately for each subtask.

• Use the en dash to indicate a relationship between two things, for instance:

  The client–server model

• Do not use the en dash to indicate a negative or an empty value or as a list bullet.

Use the hyphen (-) character in the following cases:

• To separate a prefix and the word stem when the prefix ends with the same letter as the first letter of the word stem, or when adding a prefix results in an ambiguous word:

  co-worker, re-elect

• The prefixes ex-, all-, and self- are special cases. Always use a hyphen with them:

  Ex-president, all-inclusive, self-explanatory

• Use a hyphen between attributive words in compound modifiers:

  Pre-shared key, user-specific settings, high-octane gasoline

Exclamation Points

Avoid exclamation points (!).

Periods

Periods (.) are used at the end of complete sentences that are not questions or exclamations. Use a period at the end of a list item only if the item is a complete sentence or if it continues the list-introducing sentence fragment.

Periods in M-Files Desktop, M-Files Web, and M-Files Admin

Use periods after complete sentences that are not questions or exclamations and that do not represent any of the elements mentioned in the following list:

• Dialog and tab titles

• Group box labels

• Menu items

• Button labels

• Node names in a navigation hierarchy

• Check box and radio button options

• Drop-down list options

• Group box labels

• Value and setting labels

Periods in the M-Files Mobile Apps

Include a period only after body text in message boxes and alerts.

Ellipses

Do not include ellipsis (…) in user documentation even if the ellipsis is part of the user interface text.

Use ellipses in user interface texts only to indicate that something is in progress:

`Searching…`

`Downloading the files…`

Slashes

Do not use a slash (/) as a substitute for the word or, that is, to indicate a choice between two or more alternatives. Use the word or instead.

Terminology

Avoid technical jargon and overly technical and abstract terms.

Do not use deictic expressions like today, here, below, above, or on the left. Their context can change. However, when you refer to any commands, buttons, or other elements in the user interface, make sure that the user does not have to guess where to find them, either.

The table lists the correct terms to use in documentation. Please use these terms to keep the language in documentation consistent.

A dialog is most often defined as a small window prompting for user response, whereas a window is a broader concept, essentially covering the term dialog as well.

Referring to User Interface Elements

Use a bolded font when referring to any user interface elements, like buttons, links, and titles. If font bolding is not available, use double quotes.

When referring to non-interactable user interface elements, use a definite article followed by the name of the element and then the type of the element:

The **New User** dialog is opened.

When referring to interactable user interface elements, use just the name of the element:

Click **OK**.

Sometimes, for clarity, it can be necessary to add the user interface element as an icon as well. In these cases, add the icon in parentheses right after the name of the user interface element:

Click the Create () button and then select Document.

If the icon is big, consider making the screenshot smaller.

Referring to Other Content

When you refer to content that is in the same documentation where you refer from, use the verb “see”. When you refer to external documentation, use the verb “refer”.

For more information, see _Adding Users_.

For more information, refer to _Editing Content_ in the M-Files user guide.

Abbreviations and Acronyms

Spell out the complete term the first time an abbreviation or acronym appears in the body text of the document and mention the shortened form in parentheses right after the complete term. After you have introduced and spelled out the shortening, use the shortened form throughout the rest of the document.

Here is an example:

Organizations have traditionally relied on Virtual Private Network (VPN) technology to secure access to corporate resources (such as M-Files vaults) from outside the private network of the organization.

…

Together, the HTTPS encryption and the use of a pre-shared key as a second factor in authentication provide similar security as VPN but without the complexity and compatibility challenges of VPN.

Remember to include all acronyms in the glossary of the document.

Headings

This section provides guidelines for the form and structure of headings. The following rules apply to all types and levels of headings:

• Keep headings brief and to the point, and make sure that they describe the content accurately and properly.
• Each heading must be unique. Make sure that there are no synonymous headings in a document.
• Use the title case for first, second, and third level headings.
• Use the sentence case for fourth level headings.
• Avoid using excessive or unnecessary punctuation in headings (such as parentheses, semicolons, or exclamation marks).
• Never add a period at the end of a heading.

Heading Levels

Use first, second, and third level headings for structuring your document. Use a fourth level heading only if absolutely necessary. Do not use more than four heading levels.

Heading Structure for Task Procedures

Use the gerund (the –ing form that is used for forming verbal nouns from verbs) form of a verb as the subject in task headings, instead of the sentence-initial to-infinitive phrase or a bare infinitive. Below are examples of the correct and incorrect heading structure for task procedures. Instead of using the how to structure, use the -ing form in headings as well as in the document title.

Lists

Lists are used in documentation to lay out sequential steps for a procedure or to group related pieces of information together.

The rules for lists are:

• Use lists generously, if space permits, to present information in a more digestible format than regular body text.
• Use ordered lists only when the sequence of the items is of special importance.
• Use parallel structures for the items in a list to make the list easier to read. The table gives some examples of list items with a parallel structure.

• Add a period at the end of a list item only if the list item is a full sentence, or if it continues the list-introducing sentence fragment.
• Begin a list item with a capital letter.
• Add a colon after the introductory phrase.

Procedures (Step Lists)

Use numbered lists for sequential procedure steps to indicate the order in which a task must be carried out. When writing step lists, follow these guidelines:

• Introduce the procedure with an introductory sentence in the format To <objective>:.

  For example: To add a remark:

• If a step has sub-steps, add a nested list below the step, ordered using lowercase letters as labels, followed by a period:

EXAMPLE

1. Open M-Files Admin and go to a vault.

   a) Open M-Files Admin.

   b) In the left-side tree view, expand a connection to M-Files Server.

   c) In the left-side tree view, expand Document Vaults, and then expand a vault.

• If a task has more than ten steps, try to split the task into separate, smaller tasks to make the instructions easier to follow.
• If there are multiple ways to complete a task step, use this structure:

EXAMPLE

1. Complete one of these steps:
   • Click New Login Account in the task area.

   or

   • Select Action > New Login Account.

• If necessary, add a Result section after the step list to give a description of what to expect after they have completed the task.
• You can also add the Result section after an individual step if you consider that the results are not self-evident.

1. Click OK.

   Result: A warning dialog is opened to tell you that the operation cannot be undone.

2. Click Yes to close the warning dialog and start the migration.

Localizability

• The source string should always enable the translator to create as natural a translation as possible. On the other hand, this should never compromise the quality of the source string.
• Make sure that there is enough space in the user interface for the localizations:
  • If the user interface text length is 10 characters or less, increase the space by 1.5.
  • If the user interface text length is more than 10 characters, increase the space by 1.3.

Grammar Rules

This section provides rules for the following linguistic elements:

• Phrases (a word or a group of words that functions as a single unit in the syntax of a sentence)
• Sentences (a grammatically complete series of words that consists of a subject and a predicate, typically beginning with a capital letter and ending with a period)

Proper Names

Proper names are nouns denoting product names, organization names, place names, persons, and any other names of individual entities. They are written using the initial capital letter.

Even though proper names refer to unique entities, in some cases, it can be necessary to be more specific to make the reference to the name clearer. In these situations, pair the proper name with a superordinate grouping word, such as window or button, and with a definite article preceding the name:

• The <proper name> <grouping word>

  For example: The New User dialog

Note that an entity denoted by a proper name may belong to more than one group. In such a case, just use the grouping word you need to refer to.

The HTTPS protocol

The HTTPS encryption

Write the proper name with initial capital and the grouping word with lowercase letters.

If the proper name is not followed by a grouping word (like in the M-Files software), do not use an article.

Correct: Everything in M-Files is organized by what it is instead of where it is stored.

Correct: Everything in the M-Files vaults is organized by what it is instead of where it is stored.

Incorrect: Everything in the M-Files is organized by what it is instead of where it is stored.

Do not use any special formatting for proper names, such as italics or bolding.

Genitive Case

Use an apostrophe with the letter “s” at the end of a singular noun or just an apostrophe at the end of a plural noun to denote possession for animate entities. For nouns representing inanimate entities, use the of genitive instead to denote possession. If the readability suffers, you can also denote possession with “s” for nouns representing inanimate entities. With singular animate nouns ending with “s”, also use the ‘s to denote possession.

Active Voice vs. Passive Voice

Active voice is the basic sentence structure of the English language. It is used in a clause whose subject expresses the agent (the “doer”) of the main verb. In contrast to active voice is the passive voice, which is used in a clause whose subject is the recipient of the action that the clause expresses. Below is an example of both voices.

Use active voice whenever possible.

Switch to the passive voice only when the primary focus of the clause is not on the subject. In written English, focus is primarily expressed by placing the new, non-derivable, or contrastive information at the beginning of a sentence. By switching to the passive voice, you can start the sentence with the element that would be the object of the sentence in the active voice. You can also use the passive voice when the subject of the clause need not be expressed or it is not known.

Tense

Documentation is for the most part written in the present tense, or more precisely, the simple present. Note that while the present tense generally refers to actions taking place at the present time, it can also have a reference to the future, especially to an arranged future event. Indeed, the simple present tense can be used to refer to future events that are certain to happen. This is why it is a suitable tense to use in contexts such as expected results because it is seen as more assertive than the future tense.

Here is an example:

Click New Login Account on the task pane.

Correct: The New Login Account dialog is opened.

Incorrect: The New Login Account dialog will be opened.

In the example, the present tense form can be regarded as an assertion, while the future tense form is more like a prediction.

Use future or past tenses only if it is required by the context, and if so, use only the simple forms of the past and the present tense. Note, however, that the past and the future tense are more acceptable in relative clauses than in main clauses.

Here are some examples of acceptable uses of the past and the future tense:

When this setting is enabled, any of the objects that were included in an earlier export set, but are not in the current one, will be deleted in the target vault upon import.

Thanks to the automatic updates, your M-Files installation will always be up to date.

Modal Verbs

Modals are used to express, for example, ability, possibility, permission, or obligation. Modal verbs include can, could, may, might, should, and must. In technical documentation and user interface texts, avoid using should. If something must be done, always use must.

Use can to tell what the user or the system is able to do. Do not use may or might.

Compound Modifiers

Modifiers are words that describe nouns. Modifiers in general can be used in two different syntactic positions:

• Premodifying position, in which the modifier is placed before the word that it modifies
• Postmodifying position, in which the modifier is placed after the word that it modifies

Compound modifiers are adjectives that are made up of two or more attributive words. When a compound modifier is used as a premodifier, the individual words in the compound must be joined with a hyphen. When a compound modifier is used as a postmodifier, the hyphen is not necessary, unless the word is a permanent compound and listed in the dictionary with a hyphen.

Gender-Neutral Language

Avoid gender-specific pronouns when writing documentation. There are a number of techniques for using gender-neutral language. The list below provides alternative ways of writing in a gender-neutral manner the sentence “The user can enter his e-mail address and his full name in the personal information fields.”

• Use the imperative mood:

  Enter your email address and your full name in the personal information fields.

• Use the second person:

  You can enter your email address and your full name in the personal information fields.

• Use the third-person plural forms their, them and they in place of the gender-specific her/his-, _her/him and she/he:

  The user can enter their email address and their full name in the personal information fields.

First Versus Second Person

Avoid mixing the first person (I/me/my) with the second person (you/your). For users, it can be confusing to see both person formats in the same context. Generally, use the second person when asking questions, giving instructions, or describing things to the user.

Examples:

Do you want to check it out so that you can edit it?

You can't use the same path multiple times.

In some cases, it can be necessary to use the first person to indicate the user’s ownership of content or actions:

Assigned to Me

Checked Out to Me

Contractions

A contraction is a shortening of a word, word group, or syllable, created by omitting internal letters. Can’t, for example, is a contraction of cannot.

Do not use contractions in documentation. Always write the full form of the word or word group instead. One exception is of in the phrase o’clock, in which the contraction is mandatory in contemporary use.

Numbers

Cardinal numbers (one, 2, III) are used for counting things, while ordinal numbers (first, 2nd, 3rd, IV) are used for putting things in a sequential order. The following sub-sections tells you how to use numbers in documentation.

Numerals

The symbols used for numbers (such as 1, 2, and 3) are called numerals. The rules for using numerals are:

• Never start a sentence with a numeral. Spell out the number instead.
• Spell out the numbers from zero to nine. Express numbers greater than nine in numerals.

Ordinals

• Spell out ordinal numbers from one to nine:

  First, second, third, fourth, fifth, sixth, seventh, eighth, ninth

• From the number 10 onwards, use a numeral and a suffix written in superscript above the numeral itself:

  10th, 11th, 12th, 13th, and so forth

Numbers and Units of Measurement

• Add a space, or ideally a non-breaking space, between a number and an abbreviation of a unit of measurement:

  50 GB, 120 mm

• Do not, however, use a space between a number and a symbol representing a unit of measurement:

  4.7", 60%

Negative Numbers

Negative numbers are written with a minus sign (-) immediately before the first digit of the number:

-6

-100,000

-60%

Decimal Numbers and Digit Grouping

Use the period character (.) as a decimal separator. If a number has more than three digits, separate sequences of three digits with a comma, starting from the first digit preceding the decimal point or the last digit if the number does not have a decimal point. Do not sequence the fractional part to the right of the decimal point.

Here are some examples:

122,072

7,430.25

3.14159

Currencies

When referring to monetary amounts, use one of these formats:

• Currency symbol followed by the amount with two decimal places:

  €600,000.00

• Currency code followed by a space and the amount with two decimal places:

  EUR 600,000.00

Negative amounts can be generally indicated with the words losses and deficit in descriptive texts to avoid using the minus sign (-):

A deficit of €600,000.00

Losses of EUR 600,000.00

In other text types, for instance in tabular data, negative amounts are denoted by a leading minus sign (-). Prefer using the currency symbol in conjunction with the leading minus sign, and use the currency code with a negative amount only if it is absolutely necessary:

Preferred: -€600,000.00

Non-preferred: -EUR 600,000.00

Dates

When referring to dates, use these formats:

• When there is enough space:
  • dd month yyyy
  • Do not include “0” in the one-digit day notation. That is, do not write “02 September 2020”.

  2 September 2020

• In the user interface, where the space might be limited, and in the change history table of Knowledge Base documents:
  • mm/dd
  • yyyy/mm/dd
  • In these shorter formats, include “0”.

  2020/09/02

Reference Documents

You may want to see these sources for additional information.

• Merriam-Webster Online Dictionary
• Macmillan Dictionary – American English edition
• Microsoft: User Interface Text
• Human Interface Guidelines by Apple
• Material Design: Dialogs (Android)