Writing technical content

What are you looking for?

Basics
Drafting technical content
Writing technical content
Editing technical content
Formatting technical content

This section will lay out the guiding principles of technical content, discuss the main types of technical content, and outline the process of writing and editing technical articles.

At Synergy, technical content is mostly written by the technical content team. It appears in the knowledge base and help files, throughout the application, and in a few other locations.

Basics

Someone reading technical content is usually looking to answer a specific question. That question might be broad or narrowly-focused, but either way the goal is to provide answers without distraction.

For each project, consider your audience’s background, goal, and current mood. Ask these questions:

Is the reader a prospective user, a new user, or an experienced user?
What is the reader’s goal — to complete a task? To research a topic?
Is the reader in the middle of a task and in a hurry? Could they be frustrated?

We don’t want to overload a reader with unnecessary information, choices, or complexity when we don’t have to. When relevant, prime the reader with a brief outline of an article’s focus in an introductory paragraph or section. Stick to the topic at hand. Keep sentences, paragraphs, and procedural steps concise.

Drafting technical content

If writing about a topic you’re not expert in, talk to someone who is before you begin writing. It helps to have more information than you need to decide where to focus your article.

Consider how many articles are needed and what article types will best describe a new feature or tasks to the user.

Outline your article, then write a draft. Stay in touch with your subject matter expert and revise as needed for accuracy, consistency, and length.

When you’re happy with a draft, pass it to another technical writer for peer review. Then show it to a senior writer or comms person for additional review and revisions. For new content or highly complex content, send last draft to your subject matter expert for final approval.

When writing technical content, follow the style points outlined in the voice and tone and grammar and mechanics sections. Here are some more general pointers:

Stay relevant to the title

When a user clicks the title of an article, they expect to find the answer they want. Don’t stray too far from the title or topic at hand. Use links to make related content available. If you find you’re getting too far from the intended topic, then you may need to create a separate related article.

Keep headlines and paragraphs short and scannable

Focused users often scan an article for the part that will answer their question. Be sure headlines are short, descriptive, and parallel, to facilitate scanning.

Use second-person and describe actions to a user

Technical content talks to users when support agents can’t. E.g. use pronouns ‘you’, ‘your’ and ‘yours’.

Strive for simplicity, clarity and brevity

Be as clear as possible. Use simple words and phrases, avoid gerunds and hard-to-translate expressions or words, focus on the specific task, limit the number of sentences per paragraph. If you must include edge cases or related information that’s a tangent to the topic, set it aside in a ‘before you start’ list or notes field. (A note on ‘gerunds’: this word itself contradicts ‘simplicity’ as it’s quite a hard concept to wrap your mind around if you’re not a grammar enthusiast. Read about gerunds here.)

Provide context through screenshots, GIFs and embedded videos

Screenshots and GIFs may not be necessary for every article or process, but can be helpful to orient new users. Crop screenshots tightly around the action to focus attention.

Some users like to read the answer, some like to watch and listen. If using a video, don’t assume it’s enough on its own, it should be supported with written content.

Editing technical content

We edit technical content based on three goals:

Digestibility

Cut or tighten redundancies, gerunds, adverbs, and passive constructions.
Use the simplest word.
Limit paragraphs to three sentences.

Consistency

Use the labels and terminology used in the Synergy application.
Use specific, active verbs for certain tasks.
Choose basic words and phrases for consistency across translated content.

Helpfulness

Stay conversational, using contractions when appropriate.
Avoid qualifiers that muddy meaning.
Express understanding when appropriate.
Craft clear transitions from section to section to orient the reader.

Content