This page contains the details of a technical writing project accepted for Google Season of Docs.
Project summary
- Open source organization:
- Mautic
- Technical writer:
- Swati Thacker
- Project name:
- Review and update the End-User documentation for Mautic
- Project length:
- Standard length (3 months)
Project description
My first impressions when going through the existing documentation:
Currently, the documentation is long, redundant in a lot of places, incomplete, and disorderly which might make it difficult for users to find the information they're looking for.
As a first-time user, I couldn't understand how different elements of Mautic such as Campaigns, assets, messages, categories, etc fit in together to solve a business need. I propose having a high-level conceptual topic that describes each Mautic element in 2-3 lines. This topic can in turn link to the various detailed task topics for each of these elements.
The contributing guide can be expanded to include more information such as, how to open an issue, how to suggest new content/ideas, report bugs/issues/security vulnerabilities, etc by providing links to forums, slack channels, and git repositories. Also, the style guide needs to expand to add standard typographic conventions, guidelines for images, tables, etc.
Moreover, there is quite a bit of incomplete information in Emails, Campaigns, and old/outdated information that needs updating.
The area I’d like to contribute to:
While going through the discussions on Slack channels where users interact directly with the Mautic community, I realized that Campaigns and Emails are crucial elements of Mautic. Using Mautibox for version 3, I tested the documentation on Campaigns and discovered that it needs heavy revamping. Here are some issues I found and my proposal for each:
- A Mautic user can choose from a variety of actions, decisions, and conditions while building a campaign. The documentation is missing for many actions and decisions, while there is almost no documentation for campaign conditions. We need to identify and add the missing information to the end-user doc.
- Campaigns can be simple or highly complex. The current documentation doesn't add much value to the users who're building campaigns for the first time. I propose identifying some use cases (both simple and complex) and creating sample workflows (either in the form of step-by-step tutorials, or topics within the end-user guide or walk-through videos) that a first-time user can refer to before starting to build their own campaigns.
- The information needs presentation in a more organized and orderly fashion in this section. Task and concept-based approach must be followed to increase usability. The topics can use tables to present information about actions, decisions, and conditions. The topic 'Using date triggers' feels a bit out of place. It can nest under Conditions.
In addition to Campaigns, I also tested the documentation for Emails against the UI. Here's what I propose to work on:
- Dynamic Content for Emails is available for custom code email templates (for both Templates emails and Segments emails) but currently, there is no documentation for it. Add details about what dynamic content does, and how to set it up, along with a few examples.
- Add a separate topic for Monitoring emails. This can include information about using the email widgets available on the dashboard and how they can be used to track email-related metrics and activities. Also, move info about tracking emails here.
- The documentation doesn’t make it clear that contact replies, bounce management, mailer is owner - are global configurations settings that can be configured under Email Settings. All Email settings should come under an umbrella topic. Also, many other email settings such as default frequency rules, unsubscribe settings are not documented at all. Mention which settings are mandatory or optional.
- From the Bounce management page, remove all information about Webhooks and place it in a separate topic for Webhooks. We can then provide a link to that topic from here.
Additionally: - The Dashboard topic has incomplete information about available widgets. This information is important and needs to be added as it helps users analyze and monitor their Mautic resources.
The entire documentation needs to be snagged to identify gaps. We need to revamp in terms of making the doc more approachable by our users.
How do I expect my knowledge/experience to be beneficial to this project?
After working on various issues in the Mautic documentation including adding support for the latest Mautic 3.0 release over the past month, I have been able to familiarize myself with the structure of the end-user documentation and also identify the gaps in documentation. I have spent time researching the documentation for other marketing automation tools and comparing that with the Mautic end-user documentation to understand how we can fill those gaps in our documentation. My familiarity with the HTML language, the open-source tools, and processes is an added advantage. I am currently pursuing a course in user experience research and can apply the principles to create documentation that’s more user-oriented. Also, with my experience in information architecture, I will be able to organize content and propose ideas to align our documentation with user goals. Moreover, I have a knack for expanding my knowledge of new technical domains. With 10 years of technical writing experience and my previous GSOD experience of successfully completing a project for an organization in a technical domain that was completely new to me, I am sure I’ll be able to do justice towards my contribution to Mautic documentation.