Style Overview

Basic Principles

When you finish a topic in the world of technical writing, it should pass the test of the 4 Cs. The content should be:

• Clear

• Concise

• Consistent

• Correct

If you follow the 10 Commandments listed below, you will get yourself on the right track to get to clear, concise, consistent, and correct,

🔥🔥🔥The10 Commandments of Technical Writing 🔥🔥🔥

The 10 Commandments of Writing apply to any form of written communication that you want to be clear concise, consistent, and correct. That includes web copy, UX writing, knowledge bases, guides, help, and emailed instructions to your grandma.

1. 🔥🔥🔥Use Active Voice🔥🔥🔥

Principles:

1. Clear
2. Concise

You can tell a sentence is active by identifying a clear actor. Passive: "A resolution to the problem is being investigated." Active: "We're investigating a resolution to the problem." See how the second is more human, and reassuring because someone is investigating.

It's also harder to read and understand passive voice, especially for ESL readers and people scanning (and they're all scanning).

👎 "Cloud Elements designed the APIs to have predictable, straightforward URLs and to use HTTP response codes to indicate API errors."

👍 "The APIs are designed to have predictable, straightforward URLs and to use HTTP response codes to indicate API errors."

Our writing is littered with the passive voice. See, I just did it. Take a few minutes to read up on how to recognize the passive voice and see it in your writing. The Grammar Girl wrote a great article about active voice. Raed it.

Still want some help with active voice?

You can also perform the

>>>>> gd2md-html alert: inline image link here (to images/Communication-Style0.png). Store image on your image server and adjust path/filename if necessary.
(Back to top)(Next alert)
>>>>>

zombie test . If you can add "by zombies" after the verb, you've found a passive sentence.

>>>>> gd2md-html alert: inline image link here (to images/Communication-Style1.png). Store image on your image server and adjust path/filename if necessary.
(Back to top)(Next alert)
>>>>>

The brain was eaten. (by zombies)

The guy who used to be Joe ate the brain.

2. 🔥🔥🔥Keep it Short🔥🔥🔥

Principles:

1. Concise
2. Clear

If you're reading technical content, you're probably frustrated, in a hurry, or both. You're quickly scanning for a solution and not reading every word. Acknowledge that and keep things short.

Even when longer sentences are well written, they are hard for non-native English speakers to understand. The longer a sentence is, the more decisions the reader has to make about how clauses and phrases are related. The fewer the number of subjects, verbs, and phrases in a sentence, the better.

You're goal is high information density. Pack as much information into as small a space as possible.

How?

• Use short words and sentences. Keep sentence below 25 words. Avoid very unnecessary modifiers (notice how necessary unnecessary is and now unnecessary very is?).
• Ruthlessly destroy adverbs.
• Use fewer words: 👎 We apologize for any inconvenience caused.

👍 We're sorry.

👎 In order to make an API call use your user secret.

👍 To make an API call use your user secret.

• Please don't begin a sentence with "please".

• Use simple words in your writing to make the text clearer and more readable.

  👎 Commence

  👍 Start

3. 🔥🔥🔥Make Your Content Scannable🔥🔥🔥

Principles:

1. Consistent
2. Clear
3. Concise

This is a heatmap from user eye-tracking studies of three websites. The areas where users looked the most are colored red; the yellow areas indicate fewer views, followed by the least-viewed blue areas. Gray areas didn't attract any fixations.

>>>>> gd2md-html alert: inline image link here (to images/Communication-Style2.png). Store image on your image server and adjust path/filename if necessary.
(Back to top)(Next alert)
>>>>>

Users read, or rather scan, left to right and up to down. You have to put the most critical information in the top left part of your information and make sure anything else that you want to stand out is scannable.

How?

• Use consistent topic structure. For example, a common help topic structure includes:
  • Heading
  • Concept or short description
  • Task (instructions, troubleshooting, etc)
• Use consistent grammar within your structure. Title task topics with a verb (Learn to Use Functions) and reference or concept topics with nouns (Hook Functions).
• Break information up. Use lists, tables, and short paragraphs to avoid long, unscannable sentences.
• Use ordered and unordered lists correctly: A list of things i unordered, a list of steps is ordered.

4. 🔥🔥🔥Write Well🔥🔥🔥

Principles:

1. Correct
2. Consistent
3. Clear

Your grammar does not have to be perfect, but try to write as well as you can. Poorly written content reduces confidence in its accuracy and reflects poorly on the company.

Here are some basic items to watch out for:

• See the first commandment. Write in active voice and you're well on your way to writing well.

• Avoid jargon or culturally-specific terms.

  👎 instantiate, provision, canonical, execute, abort

• Avoid ambiguity. Choose the word with the fewest meanings.

  👎 Once you write the paper, edit it.

  👍 After you write the paper, edit it.

  After and once mean the same thing, but after is more specific, has fewer meanings, and is less ambiguous.

• Avoid the future tense. It's often passive and less clear than present tense.

  👎 After the zombie eats your brains you will become a zombie too.

  👍 After the zombie eats your brains you become a zombie too.

• Avoid Latin abbreviations. They translate poorly, are usually punctuated incorrectly, and people often don't know their actual meaning. 👎 I couldn't translate the weird words, e.g., defenestrate and prestadigitation, so I just made up definitions, i.e., "to break a window" and "do a card trick."

👎 I couldn't translate the weird words, for example defenestrate and prestadigitation, so I just made up definitions such as "to break a window" and "do a card trick."

• Say it the same way every time. Don't write "sign in" in some places and "log in" in another.
• Capitalization. This should be reserved for only truly proper nouns, like Cloud Elements, Salesforce, the name of our platform. When you start capitalizing important features and components, you end up in a consistency black hole. You then have to make up capitalization rules like when to capitalize Element, Element Instance, etc. If you stick to the basics, you can remain consistent.
• Terminology. Give something a name and use it over and over. Decide on a common terminology and use it. Look in the existing documentation or the UI. Don't stray.

5. 🔥🔥🔥Test Your Content🔥🔥🔥

Principles:

1. Correct
2. Clear

How can you know that your content is correct? Test it out. Follow the steps and build something. Find what is incomplete, unclear, and inaccurate and fix it.

For the content itself, spell check and test your links.

6. 🔥🔥🔥Know the Objective🔥🔥🔥

Principle:

1. Clear
2. Consistent

Each topic, knowledge base article, blog, and course needs an objective. When beginning, ask yourself "As a reader, when I finish reading this I should be able to… (or understand…)." If it's a task-based help topic, it should describe how to do what is in the title. If it's a FAQ, it should answer the Q. If it's a troubleshooting section, it should troubleshoot a specific issue.

7. 🔥🔥🔥Be Relevant🔥🔥🔥

Principles:

1. Clear
2. Concise

Relevance is as much about what you include in your writing as what you don't include. It means stay on topic without including related, but unnecessary information. Remember, your reader is scanning. Give them exactly what they need and link out to anything related.

Progressive Disclosure is an interactive design technique where you reveal information a little at a time. Provide what a user needs where they need it, but give them the freedom to explore. Use links as guideposts to related information.

For example, if you write a knowledge base article about a specific question about formula templates include links to the existing documentation rather than adding details outside of the question you answer.

Wikipedia is a great example. Each topic is relevant on its own, but also includes links to related information. A quick look at the Wikipedia article about the greatest rock band ever gives you information about the band and provides links to the self-titled album, genre, city where they started, record labels, band members, singles, and so on.

8. 🔥🔥🔥Know Your Audience🔥🔥🔥

Principles:

1. Clear
2. Concise

Understand that you are writing for your customer, not you or the person next to you. Use terms that your customer understands. Avoid internal terms and test workflows. Put yourself in their world and how they use the product.

• Will they know what you're talking about if you refer to Element Builder when, in V2, there is no Element Builder?
• Do you know why you're writing the article, what problem it answers for the user?
• How are they going to find your article? If they search, make sure the words they'll search on are prominently used.
• What can you assume the reader knows?

9. 🔥🔥🔥Be a Human🔥🔥🔥

Principles:

1. Clear
2. Concise
3. Consistent
4. Correct

Connect with your reader as well as you can. If what you write sounds like an error message or uses the words "operate," "terminate," or "execute" you're probably not being human.

• Use the second person point of view and writer imperative sentences.
• You can do this or that.
• Avoid the term "user" at all costs!

10. 🔥🔥🔥Get Help🔥🔥🔥

Principles:

1. Correct
2. Clear

You can't catch everything yourself. Have someone look at what you wrote or use tools to help:

• Hemingway App

• Grammarly

Voice and Tone

Voice and tone are hard to establish and enforce, but overall use a tone that:

• Respects a broad audience. We have a very technical audience, but not all of them are as technical as we think sometimes. Also consider that not everyone speaks English as their first language. The more simple you write, the easier it is for an ESL reader to understand.

• Guides the audience clearly and concisely. Focus on getting the user through a task, not dumping everything on them with no clear objective.

• Educates. Tell readers what they need to know, not just what we want to say. Focus on the process or end-product, not the feature. Give them the exact information they need, and links to where to find out more.

• Talk to the reader, don't refer to them as a third party to the docs. Go ahead and say "you can..."

Basic Principles

When you finish a topic in the world of technical writing, it should pass the test of the 4 Cs. Ask yourself, is this:

• Clear
• Concise
• Consistent
• Correct

Most of the guidelines here support creating content that is clear, concise, and consistent. Being correct is on you and anyone you get to take a look at what you write.