Mautic technical writing style guide

This document draws on the Mozilla Knowledge Base writing guide and the Mailchimp Content Style Guide. Thank you to the creators of these resources and to the organizations for sharing them publicly.

Goals and principles

With every piece of content Mautic provides, the documentation and Knowledgebase aim to:

  • Empower. Help people to understand how to use Mautic more effectively by using language that informs and encourages them to make the most of Mautic.

  • Respect. Treat readers with the respect they deserve. Imagine you are in their shoes, and don’t patronize them. Remember, they’re short of time and need to find the answers to their questions quickly. Be considerate and inclusive with your language.

  • Educate. Tell readers what they need to know, and not just what you want to say. Always keep their needs at the centre of your mind when writing. Give them exactly the information they need, along with opportunities to learn more if they want to. Remember, you’re the expert. Your reader won’t have the same knowledge and expertise as you do.

  • Guide. Imagine that you are a tour guide for readers. Whether taking them through a step-by-step tutorial or teaching them how to set something up in Mautic, always communicate in a friendly, helpful way.

To achieve these goals, ensure that all content is:

  • Clear. Make sure you fully understand the topic you are writing about. Use simple words and short sentences.

  • Useful. Before you start writing a resource, ask yourself: what purpose does this serve? Who is going to read it? What do they need to know?

  • Friendly. Don’t be afraid of breaking a few rules if it makes your writing more relatable. All of the content you write, wherever it appears, should be warm and sound friendly.

  • Appropriate. Write in a way that’s appropriate to the situation. The documentation has a more formal tone, whereas the Knowledgebase is more informal. Just as you do in face-to-face situations, adapt your tone and writing style to cater to the audience you’re writing for and what you’re writing about.

  • Correct. There is a responsibility to write for Mautic, and readers expect the information to be factually correct. Always ask someone to proofread your writing before publishing.

Voice and tone

Voice

Anyone writing for the Mautic project has been in the readers’ shoes. Mautic and marketing automation can be a minefield of confusing terms, abbreviations, and complicated workflows.

When writing, adopt the tone of an experienced partner readers wish they had. Guide readers gently and point to useful resources for those starting the Mautic journey. Treat every reader seriously. Aim to educate readers without patronizing or causing confusion.

Whether people have a question they need to answer or are just learning more about Mautic, every word you write informs and encourages. Share your expertise with clarity and empathy.

This means that:

  • Use simple, clear language. The marketing world uses a lot of jargon, acronyms, and complicated terms. It’s important to simplify this language and focus on what the reader truly needs to know. Always explain terms, phrases, and concepts clearly and concisely, and encourage readers to explore further.

  • Care. You care because you know the reader’s starting point. Make their success the top priority, ensuring their businesses and organizations use Mautic to its full potential. The content must actively help them succeed and guide them every step of the way.

  • Demystify. Making the difficult and complex easy to understand. This involves clarifying marketing jargon and helping readers succeed with their marketing projects.

Tone

The tone you use varies, depending on the context. Each resource explains the expected tone in further detail below:

  • Always consider the reader’s state of mind when writing. For example, if you’re explaining how to fix an error or problem in the Knowledgebase, remember that horrible feeling when something has gone badly wrong, and you’re panicking. Imagine yourself in their shoes as they try to fix it.

  • Writing tone should be calming, clear, and concise. Provide step-by-step instructions that cover all eventualities to support the reader during their time of crisis.

  • Use an engaging, energetic tone when writing about new features. Highlight the benefits of the new features to build reader excitement.

  • Always write with the brand in mind. Mautic empowers users to do awesome things with their marketing. Freedom and flexibility define the core belief. This project is community-driven, supported by contributors worldwide who share common values. You don’t need to focus on this in every article you write, but please keep it in mind when you’re writing for any of Mautic’s technical resources.

Writing for accessibility

Make your content more accessible and usable to the broadest possible audience. Writing for accessibility goes beyond making everything available on the page as text. It also affects how you organize your content and guide a reader through the page.

Depending on the audience and country, laws may govern the required level of accessibility. At a minimum, an accessible version should be available.

Accessibility includes users with all levels of mental and physical capabilities, whether permanent, temporary, or situational, such as those with broken glasses.

Basics

The Mautic community interacts with content in various ways. The audience includes people from many cultures, and everyone should feel welcome and able to engage with the resources.

As you write, consider the following:

  • Would the language in this resource make sense to someone who doesn’t know about Mautic?

  • Does the language in this resource alienate any groups of people? Avoid gendered terms in all resources. Where a pronoun is necessary for clarity or flow, use they/them/theirs.

  • Could someone quickly understand this resource and scan to the part that’s relevant for them?

  • If the colours, images, video, or other resources aren’t visible, could the reader still understand the content in the resource?

  • Is the markup clear and structured? Do headings effectively guide the reader from step to step?

  • Does this resource work well on mobile devices with accessibility features enabled?

Guidelines

Avoid directional language

Avoid using language that implies direction based on what the reader sees on the screen, as the Mautic interface changes depending on the device and page layout.

Instead of “Select from the options on the right menu,” use “Select from these options,” and list the options.

Use headers

Headers are important for structuring the resource, but they’re also important for readers who use screen readers that can jump between them.

Always nest headers and keep them in consecutive order. Don’t skip a header level for styling reasons.

The page title should be an H1, main titles should be H2, and sub-topics should use H3 and beyond. Try to avoid excessive nesting where possible.

Use descriptive text for links

Links should provide clear descriptions of the associated action or destination and not assume that the reader has understood from the surrounding text what the action or destination is.

For example, “visit the Bounce Management page on the Documentation” gives the reader a very clear understanding of where the link leads, whereas “learn more” assumes the reader has understood the destination or action from the preceding text.

Use plain language

Write in short sentences and use familiar words. Don’t use jargon or slang. Always provide the full text of any abbreviations followed by a space, a dash, another space, and the abbreviation. For example, Single Sign-On - SSO.

Use a descriptive alt text

Alt text serves as the most basic form of image description. Include alt text with all images.

The language used depends on the image and its purpose:

  • If it’s a creative photo or supports a story but doesn’t serve a specific function or explain any information, describe the detail of the image in a brief caption.

  • If the image is serving a specific function, describe what’s inside the image in detail. If the reader doesn’t see the image, they should still be able to understand the same information as someone who did.

  • If you’re sharing an image that shows a graph or chart, include the data provided in the alt text so that readers have the same information when they don’t see the image.

Each browser handles alt text differently. You need to include an image caption where possible, in addition to the alt text.

Use closed captioning and transcripts

All videos should include closed captioning and transcripts. Information presented in videos should be available in other formats.

Be mindful of visual elements

Always aim for a high contrast between fonts and background colours in all resources.

Images shouldn’t be the only way of conveying information, as they may not load or the reader may not be able to view them. Avoid using images if writing communicates the same information just as effectively.

Resources

General writing style

Audiences

Write for a general, non-technical audience when contributing to the user documentation and the Knowledgebase. Write for the developer audience when contributing to the developer documentation.

All resources should be usable by everyone at any stage of their journey with Mautic and must avoid bias. They must not feature references to any third-party providers. If you’re unsure, always ask the Education Team before making any contributions.

Assume the person you’re writing for doesn’t know how to use Mautic or doesn’t know how to use the API without step-by-step instructions.

Article length

Knowledgebase

Keep it short. People come to the Knowledgebase looking for quick solutions. They might not care about the inner workings of Mautic. They want to know what they should do to fix their problem. Link out to documentation articles or other resources that include further details.

User and developer documentation

Fully explain all aspects of the feature and capability. Don’t assume that a user already knows or understands how something works. Link to other documentation resources as appropriate.

Clear explanations

Avoid jargon. Be specific. Use words in the title and in the article that the reader would use. If a teenager wouldn’t understand what’s in the article, write it so they would.

If you’re describing something that people may not understand - for example, how to reset file and folder permissions via SSH or how to authenticate to use the API - ensure you link to resources that explain any assumed knowledge and provide links for basic tasks such as how to connect via SSH. Also, give a full explanation for every command you use.

Doing so educates the community, reduces the chance of misunderstanding, and gives the user further resources to learn more if they wish.

You should write assuming the user has the default settings in Mautic and is using the currently available stable release.

Write descriptive heading titles

Mautic’s articles are usually comprehensive. So, it’s important to use descriptive headings to organize the contents and help people find the part of the article that they need quickly.

Take a look at your heading structure. Does it work with the introduction to give you a nice overview of the article’s scope? Do the links in the table of contents make sense?

Style tips

Mautic uses Google developer documentation style guide.

In summary, follow the tips below:

  • Active voice. Use active voice. Avoid passive voice.

  • Avoid slang and jargon. Write in plain English.

  • Avoid using single and plural first-person pronouns. Don’t use pronouns such as ‘I’, ‘my’, ‘we’, ‘us’, or ‘our’.

  • Write positively. Use positive language rather than negative language.

Title

  • When creating a resource on the user and developer documentation or Knowledgebase, ideally, your title should be less than Google’s title character count of 65 characters. Your title can be longer if necessary. However, you should include your important keywords within the first 65 characters because otherwise, search engines may not recognize them.

  • Capitalize the first word in the title, as well as proper nouns and names, but don’t capitalize every major word. Use ‘sentence’ style, not ‘headline’ style. The same applies to heading titles. See the Style guide and copy rules section below for other rules on capitalization.

  • Try to vary the way you name articles. Don’t use the same verbs or phrases in every title. For example, don’t always start articles with ‘How’ and avoid using ‘-ing’ words.

Remember that the entire explanation doesn’t have to go into the title. You can use the summary to provide the user with additional information about the article.

Working with user and developer documentation

To learn how to create and update Mautic documentation, as well as find writing tasks to work on, see Contributing to Mautic’s documentation.

Writing style for documentation projects

  • Review the contribution guidelines on User Documentation on GitHub or Developer Documentation on GitHub before contributing.

  • Use a formal writing style, similar to the way you’d expect to read instructions in a textbook.

  • Review your spelling, punctuation, and grammar.

    Tip

    Free tools such as Grammarly can be very helpful for this task.

  • Provide visual examples using images or GIFs where appropriate.

  • When writing for the developer documentation, always include at least one code sample.

  • Use headings to break down the article into relevant chunks. Links are automatically generated from heading tags, making it easy to navigate to specific parts of the article.

Working with Knowledgebase

Writing style for the Knowledgebase

  • Use a conversational writing style - an informal, active style similar to the way you’d explain to someone in person.

  • Using humor is great in person, but it’s sometimes hard or impossible to localize. So, convey emotional responses instead. Emotions like surprise and “I didn’t know that!” might be easier to include as they’re easy to understand across cultures.

  • Try to provide content that suits multiple learning styles - people learn differently. Also, everyone benefits from seeing the same content expressed in multiple ways. Work with the Education Team to include videos, images, and other media as appropriate.

  • Try to include, where appropriate, activities or step-by-step ways people can try out what you are explaining. Especially in a tutorial, it’s good to give people something useful to accomplish. It’s one thing to read instructions and understand the process, but it’s often helpful to remind and enable people to try things out.

Write a good introduction

Along with the title and the table of contents, the introduction helps people quickly determine if they’re in the right place.

  • For a tutorial or how-to article: give a summary of what readers can learn.

  • For a reference article: give a brief explanation of the feature.

  • For a troubleshooting article: give a summary of the problem and its symptoms.

When writing for the Knowledgebase, try to tell a story. Have a beginning, a middle, and an end. But don’t write a novel.

  • Beginning: this gives the reader some context. What’s this article about and why should the reader care? What’s the problem this is addressing? Keep it short.

  • Middle: the instructions go here. They should answer “How does the reader do this?”

  • End: are there any next steps to the article or feature? Tell the reader where they should go next if they want to learn more.

Organize the article effectively

The general idea here is to build skills from simple to complex while keeping the information most people need near the top.

A simple, common solution usually comes before a complex or edge-case solution.

Make step-by-step instructions easy to follow

The main thing to keep in mind when writing step-by-step instructions is to include all the actions needed to complete the task.

If, for example, you have to click ‘OK’ after selecting a preference to move to the next step, be sure to include clicking ‘OK’ as part of that step.

Some additional things to consider:

  • There are always multiple ways to achieve a result. You should always choose the most user-friendly option, using the graphical user interface and menus when possible.

  • Use complete sentences when describing how to access the user interface.

  • Include expected results when giving instructions. For example, “Click ‘OK’ to close the window.”

Organizing content

The Knowledgebase organizes content into six key areas:

  • Installation

  • FAQs

  • Tutorials

  • Marketing

  • Best practice manuals

  • Developing with Mautic

Write a good search summary

The article summary, along with the title, is the only thing that users have to judge whether an article answers their question. This establishes ‘User Confidence’, and it directly impacts click-through rates.

Even if the correct article appears at the top of the search results list, the user needs to make the mental connection between the search query and the displayed results to click through to the article.

A summary for a how-to article should include the topics covered in the article. A troubleshooting article should include symptoms. In addition, a summary should follow these guidelines:

  • Short and to the point. Remember classified ads? Write it like that. Search engines may cut off anything longer than 140 characters. If you use a longer summary, keep the important information at the beginning.

    Note

    The Knowledgebase software shows 20 characters remaining when the summary reaches 140 characters because the internal search limit is 160.

  • Don’t use “This article explains” in every summary. Vary it when possible. Some other phrases to consider:

    • This page shows you [how to perform an action]

    • This page clarifies [a complex concept or issue]

    • This article describes [a feature or concept]

    • Learn how [to achieve a specific goal]

Style guide and copy rules

Use an active, conversational style when writing for the Knowledgebase. Avoid saying things like “If a user’s email has been sent,” and instead say “If you’ve sent the email.”

Here are other common style and copy issues you may run into when writing support articles:

  • Always use terms the way they appear in the Mautic interface. For example:

    • Dashboard doesn’t have a hyphen.

    • Plugins don’t have a hyphen.

  • General computing terms:

    • The ‘Internet’ is uppercase.

    • ‘Website’ is one word. ‘Web page’ is two words.

    • ‘Log in’ and ‘log out’ are verbs. The same applies to ‘sign in’ and ‘sign out’. Don’t use ‘log into’ or ‘sign into’. For example:

      • Log in to the website.

      • Sign out of the website.

    • ‘Login’ and ‘logout’ are nouns - usually used as adjectives. For example, “Click the login button.”

    • Use ‘email’ instead of ‘e-mail’.

  • Links to mautic.org shouldn’t contain the locale.

    Use https://www.mautic.org or https://docs.mautic.org instead of https://www.mautic.org/en or https://docs.mautic.org/en.

  • Capitalize the following items:

    • Proper nouns and names, including brand names, product names, and feature names

    • The first word of a complete sentence

    • The letters of abbreviations and acronyms, unless they’re normally lowercase

    • The first word in numbered or bulleted lists

    • The name of a key on the keyboard

    • The first word of a complete sentence following a colon

    • The first word in a heading or title

  • Don’t use i.e. and e.g.

    These Latin abbreviations can confuse people. For the sake of clarity, use “in other words” or “to put it differently” instead of “i.e.” when you want to explain something differently. Use “for instance,” “for example,” or “such as” instead of “e.g.” when you want to give examples.