General Guidelines

Writing for a global audience

At Hexa, we use American English for global content. Consider the points below when writing for both global and local audiences. Following these points will help you communicate clearly.

Write with an active voice.
Write in the present tense.
Use short sentences.
Use plain language.
Avoid jargon.

Tone of voice

Writing with a tone of voice defines how we sound to our readers. In summary, your writing tone should be the following:

Clear
Confident
Caring

For more detailed examples of Hexa tone please refer to Hexa Brand Central.

Tense

Above all, be consistent. Jumping between tenses will confuse your reader. Where possible and appropriate, write in the present tense. The future tense suggests some uncertainty. In particular, avoid the verbs will and have.

Do not write:	Replace with:
When you press the button the application will send a request to the server.	Press the button. The application sends a request to the server.

Active voice

Where possible, write with an active voice. Sentences written in active voice increase clarity and ease translation efforts. When Active Voice is used, the subject acts. The verb action of the sentence creates Active Voice. Some languages use passive voice rarely, if at all, so the translation can end up sounding stilted or unnatural.

Active and passive voice examples are presented below. reference here.

Passive Voice:	Active Voice
The technical blog post was written by Daphne.	Daphne wrote the technical blog post.
A new programming language was included in the web application.	The web application includes a new programming language.
A better user experience was ensured by incorporating accessibility during the design process.	Incorporating accessibility during the design process ensures a better experience for users.

Testing your writing for active voice To test your writing for active voice append the words "by zombies" to the end of your sentence. If the sentence still makes sense, then you have a passive voice.

Start with a objective

When a phrase describes a goal and the action needed to achieve it, start the sentence with the goal.

Do not write:	Replace with:
Drag a photo to the trash to remove it from this album	To remove a photo from this album, drag it to the trash

Anthropomorphism

Anthropomorphism means to give human attributes to an inanimate object. Avoid attributing human characteristics to devices and software. Common words that indicate human characteristics and actions include behaves, refuses, wants, thinks, knows, realizes, likes, allows, lets, expects, offers, permits, and enables.

Do not write:	Replace with:
The Portal Settings pane lets you configure the Application Portal for your users.	Use the Portal Settings pane to configure the Application Portal for your users.

May / Can

When you see can in your document, consider deleting it. Can implies ability but not action. Rewrite to describe the action if possible. Don't use may. It might be interpreted as providing persmission.

Punctuation

Oxford comma

Use the Oxford comma in your text. The Oxford comma is a comma immediately preceding the conjunction (“and” or “or”) in a list of items. It’s used to separate items in a list in order to avoid misunderstanding.

Do not write:	Replace with:
Red, green, yellow, purple and black are examples of colors.	Red, green, yellow, purple, and black are examples of colors.

Semicolon

Avoid using semicolons in your writing. They usually indicate overly long sentences. Instead, split your sentence into shorter sentences.

Ellipses

In general, don’t use an ellipsis (…).

Dates

Use this format for dates: month day, year. For example, July 31, 2016. In UI, if space is an issue, use the following month abbreviations:

Jan
Feb
Mar
Apr
May
Jun
Jul
Aug
Sep
Oct
Nov
Dec

Always use two digits for the day element.
Capitalize the names of months and their abbreviations. Don't include a period with the abbreviations. Don't use ordinal numbers (such as 1st, 12th, or 23rd) to indicate a date.

Lists

Use lists to structure related information. Each list entry should contain only a single item, action, or concept.

Use a bulleted list for unordered information. For example, things that have something in common but don’t need to appear in a particular order.

Use a numbered list for sequential items or prioritized items.

List introductory text

Explain the purpose of your list with some introductory text. Use complete sentences. Do not use incomplete sentences with a colon as this style can be difficult to translate.

Do not write:	Replace with:
To sign in to the database: 1. Click Login. 2. Enter your username and password.	To sign in to the database, complete the following steps. 1. Click Login. 2. Enter your username and password.

List capitalization

Begin each item in a list with a capital letter unless there's a reason not to.

List punctuation

In bulleted and numbered lists, end each list item with a period if any item forms a complete sentence. Otherwise, do not include a period.

Do not write:	Replace with:
1. Click Login 2. Enter your username and password	1. Click Login. 2. Enter your username and password.
1. Eggs. 2. Milk. 3. Flour. 4. Add the eggs and milk to the flour	1. Eggs 2. Milk 3. Flour 4. Add the eggs and milk to the flour.

Don’t use semicolons, commas, or conjunctions (such as and/or) at the end of list items. ˜

Gerunds

A gerund (pronounced JER-und) is an English noun formed from a verb by adding -ing. Traditionally, these are used in titles and headings. Research has shown that gerunds make it more difficult to find content using search. Avoid using gerunds in titles and headings.

Do not write:	Replace with:
Getting started	Get started
Setting up the router	Set up the router
Creating a template	Create a template

Abbreviations and acronyms

Use abbreviations and acronyms sparingly. If a term is not used frequently, spell it out. On first use, include the acronym in parentheses following the spelled-out term. On subsequent mentions in the same article, page, or screen, use the acronym without spelling it out.

Avoid using an acronym for the first time in a title or heading. If the first use of the acronym is in a title or heading, introduce the acronym (in parentheses, following the spelled-out term) in the following body text. Don't spell out common acronyms like USB, FAQ, and URL.

Do not write:	Replace with:
CaaP (Conversation as a platform)	Conversation as a platform (CaaP)
Universal Serial Bus (USB)	USB
Introduction to Single sign-on (SSO) SSO is a property of access control.	Introduction to SSO Single sign-on (SSO) is a property of access control.

Idioms and colloquialisms

An idiom is a group of words established by usage as having a meaning not deducible from those of the individual words (for example, over the moon, see the light). Colloquialism is the use of informal words and phrases (for example, bamboozle). Eliminate idioms and colloquialisms from your technical communications. They can be confusing for non-native English speakers and hard to localize.

Do not write:	Replace with:
get rid of	discard, delete
for good	permanently
figure out	understand
go ahead	proceed, begin

Link text

Link text, also referred to as inline text or anchor text, is a link to another page embedded in a line of text. For example, "The Hexa website has lots of useful links". Make your link text useful. Use a phrase that describes what the reader will see after following the link.

Create your link text to follow one of these formats:

Use the exact title of the linked-to page, capitalized the same way the title is capitalized.
Use a description of the linked-to page, capitalized like ordinary text instead of like a title.

To improve scannability, keep link text short and concise. Avoid using an excessive amount of links in a page.

Do not write:	Replace with:
Click here for more information on time calculations.	Use The World Clock - Worldwide to calculate time differences.
Follow this link to learn about rubber ducks.	Learn more about rubber ducks, it'll make your life better.