Education Team

Missions and expectations of the Education Team

The core mission of the Education Team is to empower the Mautic community by maintaining comprehensive, high-quality documentation and learning resources.

The team ensures that all resources are high-quality, easy to understand, and accurate for each release. They also monitor the Community Forums to identify recurring issues, common questions, and gaps in existing documentation. The team continuously works to improve learning resources for both new and experienced users.

The main objective is to improve the user experience by providing clear, comprehensive support and ensuring that all documentation and essential resources are available in multiple languages for a global audience.

General tasks for the Education Team

  • Maintaining high-quality and current documentation

    • Keep the documentation clear, accurate, and consistently high-quality.

    • Ensure that the documentation is up to date with new releases.

    • Improve the experience of Mautic Users by ensuring that the documentation is comprehensive and highly usable.

    • Help marketers contribute their existing content to the Mautic Knowledgebase.

  • Forums analysis & resource development

    • Monitor the Mautic Community Forums to proactively identify recurring questions, common issues, and persistent themes that indicate documentation gaps.

    • Develop high-quality documentation and learning resources based on the solutions to the frequently asked questions.

  • Enhancing user learning and global accessibility

    • Improve the resources available for new and established Users to learn how to use Mautic.

    • Ensure multilingual availability for documentation and key user resources.

Forums

Quality of contributions

  • Are the answers to the asked questions correct? Ensure indication of the correct solutions if this is the case.

  • Is it an often asked question? Then, add it to the documentation.

  • Are there multiple posts about the same thing? Then, merge into a mega-post.

Forums rules

  • Which rules are appropriate

  • Which rules are relevant / needed to keep the Forums working fine

  • Moderate Forums or assign moderators

  • Moderate posts by themselves

  • Elect moderators who moderate the Forums for them

  • Redirect all Support questions from Slack to Forums

  • Very visible hint in Slack that support questions aren’t answered there

  • Manually moderating Slack & moving stuff to Forums

  • Automatically moving stuff to Forums?

Documentation

Sources

  • User Documentation describes key concepts of Mautic and provides instructions for using and contributing to Mautic.

  • Knowledgebase provides a database of tutorials, FAQs, and how-to articles.

  • Developer Documentation details about the Mautic API, Webhooks, Themes and Plugin development.

  • Community Handbook is a central point of call for documentation on the organization and management of the Mautic community.

Quality

  • Maintaining a high quality

  • Review the accuracy of the documentation

  • Keeping it easy to understand

Completeness

  • Add missing topics to the documentation

  • Proactively reviewing site/Google searches and identifying topics to write if there are missing areas

  • Manage issue queue on the documentation and community handbook GitHub repositories

  • Adding highly requested Forums questions

Up to date

  • Ensuring that the documentation is up to date with major releases

  • Document changes coming with those releases

  • Merge PRs when they come in for new features

Languages

  • Keeping native translations accurate

  • If necessary, add more translations

Style guide

The Mautic Style Guide recommends best practices to achieve a consistent style, voice, and tone across all documentation.

Any Technical Writer - or other contributor - can make suggestions for documentation style updates.

Educational blog content

  • Curating and writing content for the community blog

  • Curating and writing how-to articles and tutorials for the Mautic Knowledgebase

Mautic app and website/marketing internationalization

  • Own Transifex and appropriate workflows

  • Manage multilingual marketing materials - for example, website, fliers, etc.

  • Work tightly with Community, Product and Marketing teams

Profiles of contributors needed in the Education Team

The Education Team needs insights from:

  • New Users

  • Established Users

  • Administrators

  • Developers

  • Theme builders

  • Business owners considering Mautic

  • Business buyers/procurements

The Education Team needs people with skills as:

  • Trainers

  • Marketers

  • Video producers

  • Content creators

  • Documentation writer

  • Editors

  • Translators

Note

Would you like to get involved in this team? Join #t-education on Mautic Community Slack.

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.

General guidelines applicable to all resources

Goals and principles

The Education Team’s goals and principles are 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 the Education Team, 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 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 a more bubbly, energetic tone if you’re writing about an exciting new feature.

  • 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 being inclusive of all mental and physical capabilities, whether situational - broken glasses - or more permanent.

Some basic requirements

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 might be using a screen reader that can jump between headers.

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 the abbreviation in brackets. For example, Sender Policy Framework - SPF.

Always 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.

Always include closed captioning and transcripts for videos

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

Be aware 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.

Accessibility 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.

Clear explanations

If you’re describing something that people may not understand - for example, how to reset file and folder permissions via SSH in the User Documentation, 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 based on the assumptions that the user has the default settings in Mautic and is using the currently available stable release.

Use descriptive heading titles

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

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?

To summarize, you should follow these guidelines:

  • When writing for the 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.

  • When writing for the User Documentation or Developer Documentation, ensure that you 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.

  • Use headings to organize your content and allow people to find the relevant part of the resource quickly.

  • 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.

Read the next section for more comprehensive, platform-specific guidelines.

Technical guidelines

General guidelines
Title

  • When creating a resource on the User Documentation or Knowledgebase, ideally, your title should be less than Google’s title character count of 65 characters. Your title can be longer than this if necessary. But include your important keywords in the first 65 characters; otherwise, search engines won’t see 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.

Work with User and Developer Documentation

  • Read the /contributing/contributing_docs_rst for an overview of how the documentation works and the syntax you should use.

  • Check out the Education Team’s Jira board for tasks relating to the User Documentation.

Work with Knowledgebase

Writing for User or Developer 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. Please review your spelling, punctuation and grammar. Tip: free tools such as Grammarly can be very helpful for this task.

  • Try to provide visual examples using images and videos where appropriate - work with the Education Team, who can support you with this.

  • 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, allowing easy navigation to specific parts of the article.

Writing for the 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 brief summary of what readers can learn.

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

  • For a troubleshooting article: give a brief 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. This 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 pick the most user-friendly way by 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 in the Knowledgebase

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]

    • his 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 - if you don’t see your issue here, there’s also a Mautic Style Guide:

  • 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.

  • Don’t use serial commas in a list of items.

    For example, use “Extensions, themes and plugins,” without the serial comma, not “Extensions, themes, and plugins.”