Our technical content appears primarily in our guides and tutorials. 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 customer, a new customer, or an experienced customer?
- What is the goal of the customer? To complete a task? To research a topic?
- Is the customer in the middle of a task? Are they in a hurry? Could they be frustrated?
We don’t want to overload our audience with unnecessary information, choices, or complex ideas or phrases when we don’t have to. This is particularly critical when a customer may be new and/or frustrated.
When relevant, provide 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. Mailchimp technical content is built from templates, which serve different purposes and readers. Templates should be considered guidelines and are not intended to be prescriptive. We may deviate from or combine elements of different templates to best serve the reader.
Here are some examples of article templates we use.
| Article Template | User Type | Goal |
|---|---|---|
| Pathfinder | prospective, new, intermediate | Orientation. Bundle topics and provide links to relevant tutorials or general reference. |
| General Reference | prospective, new, intermediate | Introduction. Provide a high-level explanation of what the feature is, how it works, and its benefit to the user. Include 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 prerequisites, and clear step-by-step instructions. |
Guidelines
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 other goals and pointers to keep in mind.
Stay relevant to the title
When a reader 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 readers often scan an article for the part that will answer their particular question. Be sure headlines are short, descriptive, and parallel, to help scanning.
Use second person and describe actions to a reader
Technical content talks to customers 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, videos, and GIFs
Screenshots, videos, and GIFs may not be necessary for every article or process, but can be helpful to orient new customers. Crop screenshots tightly around the action to focus attention.
Formatting technical content
Technical content uses organization, capitalization, and other formatting to help convey meaning. Although articles are organized differently, some formatting tips are consistent throughout all technical content.
Capitalization
Capitalize proper names of products, features, pages, tools, and teams when directly mentioned. In step-by-step instructions, capitalize and bold navigation and button labels as they appear in the app.
- Mailchimp
- Compliance Team, Billing Team
- Navigate to the Reports page.
- Click Create.
Headings
Organize article content with H2s and H3s. Use H2s for higher-level topics or goals, and use H3s within each section for supporting information or tasks.
Article title: About Landing Pages
- H2: How landing pages work in Mailchimp
- H2: How to use landing pages
- H2: Resources
- H3: Get inspired and learn best practices
- H3: Create a landing page
- H3: Learn about reports
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. If an unordered list comprises more than 10 items, use a table instead.