Education Team
Missions and expectations of the Education Team
keep the forum clean and constructive,
keep the documentation to be high quality, understandable, and accurate,
improve the resources available for new and established Users to learn how to use Mautic,
ensure multilingual availability.
General tasks for the Education Team
Help marketers to contribute their existing content to the Mautic Knowledgebase
Ensure that the documentation is up to date with new releases
Improve the experience of Mautic Users by ensuring that the documentation is of high quality and comprehensive
Moderate the Mautic Community Forums and provide content to answer FAQs
Improve the resources available for new and established Users to learn how to use Mautic
Forum
Quality of contributions
Are the answers to asked questions correct? Ensure indication of the correct solutions if this is the case.
Is it an often asked question? → Add to documentation
Are there multiple posts about the same thing? → Merge into a mega-post
Forum rules
Which rules are appropriate
Which rules are relevant / needed to keep the forum working fine
Moderate Forum / Assign Moderators
Moderate posts by themselves
Elect moderators who moderate the forum 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 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 forum 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 that aims to bring about 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, tutorials for 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 need insights from:
New Users
Established Users
Administrators
Developers
Theme builders
Business owners considering Mautic
Business buyers/procurements
The Education Team need 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.
End-User Documentation
One of the projects that the Education Team are responsible for is the End-User Documentation.
This section contains useful information, guides and resources for people interested in contributing to the End-User Documentation.
Technical writing style guide
This document is based 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 which 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 are 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 will not have the same knowledge and expertise as you do.
Guide. Imagine that you are a tour guide for our readers. Whether you’re taking them through a tutorial step by step or teaching them how to set something up in Mautic, always communicate in a friendly, helpful way.
In order to achieve our goals, we ensure that all of our 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. We’re all human beings, so make sure that you write like one. Don’t be afraid of breaking a few rules if it makes your writing more relatable. All of the content we write, wherever it appears, should be warm and human.
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 for the audience you’re writing for, and what you’re writing about.
Correct. There is a responsibility in writing for the Education Team, and an expectation from our readers, that the information is factually correct. Always ask someone to proofread your writing before publishing.
Voice and tone
Voice
Most of us writing for the Mautic project have been in the shoes of our readers. We know what it’s like to be where they are. We know that Mautic and Marketing Automation can be a minefield of confusing terms, abbreviations, and complicated workflows.
When we write, we speak like the experienced partner that we all wish we’d had, holding our hand and pointing us to the useful resources when we were back at the start of our Mautic journey. We treat every reader seriously. We want to educate our readers, without patronizing them or confusing them.
Whether people have a question they need to answer or are just learning more about Mautic, every word we write informs and encourages. We share our expertise with clarity and empathy.
This means that:
Use simple, clear language. We understand that the world of Marketing is riddled with buzz words, acronyms and confusing terminology. We strip this back and get down to what the reader needs to know. We always explain terms, phrases and concepts in a clear and concise way, and encourage our readers to explore further.
Care. We’ve been where our readers are. We care about their success. We want their businesses and organizations to use Mautic to its full potential. We care deeply about helping them to succeed and our writing helps them every step of the way.
Demystify. We make the difficult and complex easy to understand. We bring clarity to marketing jargon, and help our readers succeed with their marketing projects.
Tone
The tone we use varies depending on the context. Each resource will explain the expected tone in further detail below.
Always consider the reader’s state of mind when writing.
As an example, if you’re explaining how to fix an error or problem for the Knowledgebase, remember that horrible feeling when something has gone badly wrong and you’re panicking. Put yourself in their shoes as they try to fix it.
Your writing tone will need to be calming, clear, concise, and have step-by-step instructions covering all eventualities to support the reader in their time of crisis.
If you’re writing about an exciting new feature, you might use a more bubbly, energetic tone.
Always write with the brand in mind. Mautic is about empowering our users to do awesome things with their marketing. We believe in freedom and flexibility. We’re community-driven with contributors all over the world 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 our technical resources.
Writing for accessibility
We want to make our content more accessible and usable to the widest possible audience. Writing for accessibility goes beyond making everything available on the page as text. It also impacts how you organize your content, and how a reader is guided through the page.
Depending on the audience and country, there may be laws in place governing the level of accessibility required. 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
Our community interact with our content in a variety of ways. They come from many different cultures, and we want everybody to feel welcome, and be able to engage with our 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? We don’t use gendered terms in any of our resources. Where a pronoun is considered important for the flow of the resource we 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? Are headings structured to ensure that the reader is guided from step to step?
Does this resource work well on mobile devices with accessibility features enabled?
Guidelines
Avoid directional language
Avoid using language which infers a direction based on what the reader sees on the screen. Mautic’s interface will change depending on the device being used and the layout of the page.
Instead of “Select from the options on the right menu,” use “Select from these options,” and list the options.
Use headers
As already mentioned, headers are important to structure the resource, but they’re also important for readers who might be using a screen reader which can hop between headers.
Headers must always be nested and consecutive. Don’t skip a header level for styling reasons.
The page title should be H1, main titles should be H2, and sub-topics use H3 and beyond. Try to avoid excessive nesting where possible.
Use descriptive text for links
Links should provide clear descriptions on the associated action or destination and not assume that the reader has understood from the surrounding text what the action or destination will be.
For example, “visit the Bounce Management page on the Documentation” gives the reader a very clear understanding of where the link will take them rather than “learn more,” which assumes the reader has understood the destination or action from the preceding text.
Use plain language
Write in short sentences and using 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
The alt text is the most basic form of image description, and should be included with all images.
The language used will depend on the image being included 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 be able to understand the same information as someone who had seen the image.
If you’re sharing an image which 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 be seen. Avoid using images where the same information could be communicated as effectively in writing.
Accessibility resources
General writing style
Audiences
Write for a general, non-technical audience when contributing to the End-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 shouldn’t be biased or 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 End-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, ensure that you explain the commands being used fully.
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 are 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 scope of the article? 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 just want to know what they should do to fix their problem. Link out to documentation articles or other resources which might include further details.
When writing for the End-User Documentation or Developer Documentation, ensure that you fully explain all aspects of the feature or functionality. Don’t make assumptions that a user will already know or understand how something works. Link to other documentation resources as appropriate.
Use headings to organize your content and allow people to quickly find the relevant part of the resource.
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 contained within the article, write it so that they would.
Read the next section for more comprehensive guidelines, which are platform-specific.
Technical guidelines
General guidelines
Title
When creating a resource on the End-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 make sure your important keywords are included in the first 65 characters, otherwise, they’re not seen in search engines.
Capitalization. The first word in the title should be capitalized, as well as proper nouns and names, not 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 give the user additional information about what’s in the article.
Work with End-User and Developer Documentation
To learn how to create a new resource, see Create a new Documentation resource.
See Contributing to Mautic’s documentation for an overview of how the documentation works and the syntax that should be used.
Check the Education Team’s Jira board for tasks relating to the End-User Documentation.
Work with Knowledgebase
To learn how to create a new resource, check the contribute to the Knowledgebase article.
Check the Education Team’s Jira board for tasks relating to the Knowledgebase.
Writing for End-User or Developer Documentation
Writing style for Documentation projects
Review the contribution guidelines on User Docs 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 check 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 created based on heading tags, which allows for 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 we recommend instead conveying emotional responses. Emotions like surprise and “I didn’t know that!” might be easier to include as they are 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 is what people will use to quickly determine if they’re in the right place.
For a tutorial or how-to article: give a brief summary of what things can be learned.
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 I care? What’s the problem this is addressing? Keep it short.
Middle: the instructions go here. This should answer “How do I 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 try to build skills from simple to complex while trying to keep the information needed by most people near the top.
A simple, common solution would usually come 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 be careful 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. We should always pick the most user-friendly way by using the graphical user interface and menus when possible.
Use full 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
We currently have six key areas in which we organize content for the Knowledgebase:
Installation
FAQs
Tutorials
Marketing
Best practice manuals
Developing with Mautic
Write a good search summary
The article summary along with the title are the only things that the user has to judge whether or not an article will answer their question. We call this ‘User Confidence’ and it directly impacts click through rates.
Even if we serve the correct article at the top of the search results list, the user needs to make the mental connection between the search query and the results we display in order for them 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 try to 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 KB software will show 20 characters remaining when the summary reaches 140 characters because the internal search limit is 160.
Don’t use wiki markup. Just plain text in any of the SEO fields.
Don’t use “This article explains” in every summary. Vary it when possible. Some other phrases to consider:
This page shows you …
This page explains …
This article describes …
Learn how …
Style guide and copy rules
You should use an active, conversational style when you write 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 doesn’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. Example: ‘Log in to the website.’ The same applies to sign in and sign out. Don’t use ‘log into’ or ‘sign into.’
Login and logout are nouns - usually used as adjectives. Example: ‘Click the login button.’
Use email instead of e-mail.
Links to
mautic.orgshould not contain the locale.Use
https://www.mautic.orgorhttps://docs.mautic.orginstead ofhttps://www.mautic.org/enorhttps://docs.mautic.org/enCapitalize 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 are 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 in a different way. 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.”