This document is based on the Mozilla Knowledgebase Styleguide and the Mailchimp StyleGuide. Thank you to the creators of these resources and to the organizations for sharing them publicly.
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 is 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.
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:
We 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.
We care. We have 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.
We 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.
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 are 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.
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.
Our community will interact with our content in a variety of ways. They will 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:
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).
As already mentioned, headers are important to structure the resource, but they are also important for readers who might be using a screenreader which can hop between headers.
Headers must always be nested, and consecutive. We do not 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.
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.
Write in short sentences and using familiar words. Do not use jargon or slang. Always provide the full text of any abbreviations followed by the abbreviation in brackets (for example Sender Policy Framework (SPF)).
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:
Each browser will handle alt tags differently - include an image caption where possible in addition to the alt text.
All videos should include closed captioning and transcripts. Information presented in videos should be available in other formats.
Always aim for a high contrast between fonts and background colours in all resources.
Images should not 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.
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.
We want our resources to be usable by everyone, at any stage of their journey with Mautic. Our resources should not be biased or feature references to any third party providers. If you are 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.
If you are describing something that it is possible people may not understand (how to reset file and folder permissions via SSH in the end-user documentation, or how to authenticate to use the API for example) 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.
This educates our community, reduces the chance of misunderstanding, and gives the user further resources to learn more if they wish.
We should write based on the assumptions that the user has the default settings in Mautic and are using the currently available stable release.
Our 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. Do not make assumptions that a user will already know or understand how something works. Link to other documentation resources as appropriate.
Use headings to organise 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 is contained within the article, write it so that they would. See the next section for a more extensive guide.
Read the next section for more comprehensive guidelines which are platform-specific.
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 will not be 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 is in the article.
Each article created or edited in the End-User Documentation and Knowledgebase user interface will have a tab called ‘SEO’. In this tab, you can override the default title, description and other fields to ensure maximal optimisation for search engines.
If you do not override these fields, the defaults will be used.
When you create an article for the End-User Documentation or the Knowledgebase, Grav will automatically create a slug based on the item title (the end of the URL for the article). Spaces are rendered as dashes.
The slug should be consistent with the title, but given the tighter space restraint, doesn’t need to be the same. Be sure to check the end of the auto-generated slug once the item is saved. Sometimes a word gets cut off or it ends in a dash - please fix things like that!
The slug can be overridden under the ‘Advanced’ tab. Simply select the checkbox next to ‘slug’ and enter your preferred slug for the article. Note you should not include any paths before the slug for categories/structure, just the article slug.
To learn how to create a new resource, see Create a new Documentation resource.
See Contributing to the Documentation for an overview of how the Documentation works and the syntax that should be used.
Check the Education Team’s Jira board for outstanding tasks relating to the End-User Documentation.
The Developer Documentation uses Slate, and does not have a front-end user interface. Please make any changes via a Pull Request (PR) to the repository.
Check the [Education Team’s Jira board][edu-team-jira-devdocs] and the Product Team’s Jira board for outstanding tasks relating to the Developer Documentation.
To learn how to create a new resource, see Create a new Knowledgebase resource.
See Contributing to the Knowledgebase for an overview of how the Knowledgebase works.
Check the Education Team’s Jira board for outstanding tasks relating to the Knowledgebase
Review the contribution guidelines for the End-User Documentation and Developer Documentation 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 (free tools such as Grammarly can be very helpful with this!)
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.
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.
Along with the title and the table of contents, the introduction is what people will use to quickly determine if they are in the right place.
When writing for the Knowledgebase, try to tell a story. Have a beginning, a middle and an end. But don't write a novel!
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.
So a simple, common solution would usually come before a complex or edge-case solution.
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 in order 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" and the window will close.).
We currently have six key areas in which we organise content for the Knowledgebase:
Grav organises these by nesting the articles underneath the top-level category. If a top-level category is required please use the ‘blog’ page type (clone an existing one for a quick setup!), if you’re writing an individual article, use the ‘item’ page type.
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:
Like we said before, 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:
General computing terms:
Links to Mautic.org should not contain the locale:
Capitalize the following items:
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".
Found errors? Think you can improve this documentation? edit this page