In April of 2020, Mautic applied for the Season of Docs, a project supported by Google that brings together technical writers and open source communities to work on a project for a couple of months. As this was the second year of the programme running we were excited to be selected as an organisation.
If you want to read more about our application, feel free to read the first blog article introducing the Season of Docs.
The Projects
Project End-User Documentation
The team: Ruth Cheesley, Norman Pracht, Swati Thacker
The first of our Season of Docs projects involved making some targeted improvements to the End User documentation at https://docs.mautic.org. This is usually the first place that Mautic users come to learn about working with Mautic, but much of the content was not well organised and some was out of date.
A quick rundown of how the End-User Documentation project went
In our first kick off calls we discussed what areas we should focus on and how to prioritise the tasks ahead of us.
We decided to target the main landing page which welcomes people to the docs and also includes information on how to contribute to improving the documentation. After this, we would focus on improving and restructuring and improving content in the Campaigns section.
Swati Thacker spent a good amount of time becoming familiar with Mautic and learning what parts of these documentation resources needed to be updated, alongside getting familiar with using Git to make her contributions.
During the course of this project Swati noted that we have a lot of spelling, grammar and style inconsistencies in the content, and suggested that we consider implementing a linter. Much like the code style checks we use to make sure that the code is written correctly, a linter would check new pull requests to the documentation for spelling, grammar and writing style against predefined configurations.
We are currently in the final stages of reviewing the implementation of the Vale linter using the Google Style Guide as our base.
Project Knowledgebase
The team: Leon Oltmanns, Kevin Rundle, Favour Kelvin
The second project resolved around the creation of a Knowledgebase for the Mautic open source project. A Knowledgebase is a collection of best-practises, how-to’s and tutorials, covering different aspects of Mautic. Knowledge that is important to share but not really suiting the narrow ties of the Documentation.
And not to spoil the end, but the Knowledgebase project was a huge success. Now to be found under https://kb.mautic.org/ sits the newly found Mautic Knowledgebase.
A quick rundown of how the Knowledgebase project went
At the beginning of the Season of Docs we, Leon Oltmanns and Favour Kelvin had a couple of kickoff meetings, discussing a rough timeline as well as a scope for the project. Which parts of the Knowledgebase do we need to “Go-Live”, what would be realistic to achieve in the months of working together, how do we process quality assurance and testing etc.
We pretty quickly had a baseline that we worked on using a Grav based page. From there we started working on the website while also writing articles at the same time. Favour Kelvin, as an experienced technical writer, wrote a remarkable proportion of the articles found in the knowledgebase. Leon spent most of his time configuring and building the website and coordinating with Favour, which articles should be written next.
This is how we proceed to work for a couple of months until the knowledgebase was ready to be launched in its first presentable iteration!
Since then the Knowledgebase grew step-by-step and if you, dear reader, want to contribute your knowledge to the Knowledgebase, you can do it right here.
Conclusion
We are delighted with the progress made by both of our technical writers who were new to Mautic and quickly jumped in to get started on their projects. Swati and Favour have both made substantial contributions during their projects and the Mautic Community has benefitted from their skills and enthusiasm for improving our documentation.
You will still see them around the community even after the projects have completed - Favour has now stepped up to lead the Education Team and Swati is working with us to refine the Vale linter on the main documentation project.
A big thank you to Google for organising this programme and to Swati and Favour for their awesome work!
