Writing Technical Content

At Overloop, technical content is mostly written by the product team. It appears in the Knowledge Base, throughout the app, and in a few other locations. 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.

Basics

Someone reading technical content is usually looking to answer a specific question. That question might be broad or narrowly-focused, but either way our 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 goal of the reader? To complete a task? To research a topic?

• Is the reader in the middle of a task? Are they in a hurry? Could they be frustrated?

We don’t want to overload a reader with unnecessary information, choices to make, or complex ideas or phrases, when we don’t have to. This is particularly critical when a user may be new and/or frustrated. When relevant, prime the reader with a brief outline of an article’s focus in an introductory paragraph or section, and stick to the topic at hand. Keep sentences, paragraphs, and procedural steps focused and concise.

Types of technical content

Technical content articles vary in target audience, goal, and tone. Overloop technical content is built from 8 templates, which serve different purposes and readers.

Article Template	User Type	Goal
Best Practices	all	Context. Make connections between Overloop and outbound as a whole.
Cheat Sheet	intermediate, advanced	Reference. Include all available scenarios.
Getting Started	prospective, new	Overview. Include brief outline of topic, uses, benefits, and related topics. Use links to best practices, cheat sheets, and feature overviews.
Policy	all	Education. Provide digestible information about critical legal policies and procedures.
Pathfinder	prospective, new, intermediate	Orientation. Bundle topics and provide links to relevant tutorials.
Troubleshooting	new, intermediate, advanced	Support. Outline expected behavior and include potential causes of unexpected behavior; group by cause or topic.
Tutorial	new, intermediate	Guidance. Briefly describe a task, provide a roadmap and pre-requisites, and clear step-by-step instructions.
Warning	new, intermediate, advanced	Assurance. Outline warning type, explain why something happened, and include next steps for users.

Guidelines

Drafting technical content

Before you begin writing a new article, reach out to a subject matter expert at Overloop (like an engineer, tester, designer, researcher, or technical support advisor) to get as much information as possible. You may only use a small portion of what you learn, but 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 (the developer, most of the time) and revise as needed for accuracy, consistency, and length.

When you’re happy with a draft, pass it to another teammate for peer review. For new content or highly complex content, send last draft to your subject matter expert for final approval.

Writing technical content

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, too.

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 but related article.

Keep headlines and paragraphs short and scannable

Focused users often scan an article for the part that will answer their particular 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.

Strive for simplicity and clarity

Be as clear as possible. Use simple words and phrases, avoid gerunds and hard-to-translate idioms or words, focus on the specific task, limit the number of sentences per paragraph. If you must include edge cases or tangentially related information, set it aside in a Before You Start list or Notes field.

Provide context through embedded screenshots and GIFs

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.

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 Overloop app.

• Use specific, active verbs for certain tasks.

• Choose basic words and phrases to facilitate 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.

Formatting technical content

Technical content uses organization, capitalization, and other formatting to help convey meaning. Although different articles are organized differently, some formatting tips are consistent throughout all technical content.

Capitalization

Capitalize proper names of Overloop products, features, pages, tools, and team names when directly mentioned. In step-by-step instructions, capitalize and italicize navigation and button labels as they appear in the app.

• Overloop, Email Finder

• Workflows page, Lists page

• Support Team, Product Team

• Navigate to the Tasks page.

• Click Save & Close.

Headings

Group article content with H2s and H3s. Use H2s to organize content by higher-level topics or goals, and use H3s within each section to separate supporting information or tasks.

• Upload a List

  • Format your CSV File

  • Import your CSV File

  • Match Fields

• Best Practices for Lists

  • List Collection

  • List Management

  • Email Content and Delivery

Ordered Lists

Only use ordered lists for step-by-step instructions. Separate steps into logical chunks, with no more than 2 related actions per step. When additional explanation or a screenshot is necessary, use a line break inside the list item.

Unordered Lists

Use unordered lists to display examples, or multiple notes in a Notes block. If an unordered list comprises more than 10 items, use a table instead.