Last year, Mautic took part in 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.

We are excited to apply again as an organisation.

About the Google Season of Docs

You may have heard of the Google Summer of Code before – this is a similar program but applies specifically to documentation. The goal of the Google Season of Docs is

To provide a framework for technical writers and Open Source projects to work together towards the common goal of improving an Open Source project’s documentation.

For technical writers who are new to Open Source, this presents an opportunity to make your first contributions and get started with supporting an Open Source project. For technical writers who might already be contributing in Open Source, the program could be a new way of working together, or an opportunity to explore new projects.

The program brings together technical writers with an Open Source community for a period of a few months, bringing their writing expertise to the project’s documentation while learning about the project, community and technology behind it.

Together, we raise public awareness of Open Source documentation, technical writing, and how we can work together to the benefit of the global Open Source community.

The Education Team are excited to be proposing three projects for consideration by the Google Season of Docs team. All three projects are key to helping our users – whether developers, end-users or marketers – better understand how to work with Mautic. Read more about the project proposals below, and if you’re interested in learning more do join the Education Team channel on Slack!

Project Idea 1: Improve and update the Mautic Developer Documentation

Problem

• Mautic’s Developer Documentation is outdated and in many areas has incorrect code examples which have not been updated to support Mautic 3.x. This project will primarily focus on auditing and updating the documentation itself.

• The underlying tooling based on Slate should be updated – some work has started on this but we have not got the resources within the community to complete the task. This is a sub-task – a nice to have if you have the skills to help with this.

• There is some end-user focused documentation which should be extracted from the Developer Docs and moved over to the End-User documentation (specifically around themes). This is nice to have and will involve working with the Education Team to transfer the content.

• As a stretch goal, we can consider building out a developer portal. Initial ideas and scoping are being tracked in this Jira issue and this Google Doc.

Measuring project success?

• Resolution of outstanding issues in the issue queue and merging of outstanding pull requests (measured here for issues and here for pull requests),

• Updating Slate to the latest version and deploying with Github Actions when pull requests are merged.

• New contributions to the docs by demonstrating best practices and improving the docs on how to contribute (measured here ),

• An increase in the number of new developers working with Mautic (measured in our Github metrics, downloads and mailing list signups),

• Long term – improved developer sentiment (measured in Community CRM).

What skills would a technical writer need to work on this project?

Must have:

• Familiarity with GitHub, Slate (or comparable tools) and API documentation,

• Experience with Mautic and the Mautic API (or willingness to get up to speed quickly),

• Optionally experience with Grav and Markdown-based content for the stretch goal,

• Strong collaboration skills – you will be working with several teams and having to dig into the codebase and work with the Core Team to ensure that the documentation is top-notch!

Mentors

• Alan Hartless will be the primary mentor for this project,

• Ruth Cheesley can help with answering questions about Mautic and review pull requests for grammar, content and style,

• Favour Kelvin, Education Team Lead, can review pull requests,

• Dennis Ameling can help with Github automation and updating Slate.

Contact info

• Technical writers interested in working on this project should send an email to seasonofdocs@mautic.org – Please do not contact the mentors directly unless you have a specific question to ask them. Please include links to your technical writing work or portfolio/resumé/CV.

Project Idea 2: Implementing multilingual functionality on the Mautic End-User documentation

Problem

• Mautic is used by a worldwide audience and is available in 64 languages, but the documentation is currently only available in English.

• We would like to implement the facility to add other languages to the End-User Documentation.

• This project will involve implementing the technical details (language switcher etc) and working with the community to run some sprints to get the first translation completed and ready to launch. It will also involve translating technical documentation into Portuguese.

How would we measure success?

• An additional language available in the Mautic Documentation (starting with Portuguese as that is by far the most popular language),

• Increased contributions to the Documentation from new contributors in languages other than English by 50%.

What skills would a technical writer need to work on this project?

Must have:

• Experience with technical writing in languages other than English (preferably Portuguese),

• Familiarity with Github (or willingness to work through GitHub tutorials and learn the basics outside of this project).

Mentors

• Ruth Cheesley and Favour Kelvin will be the primary mentors for this project,

• Rodrigo Demetrio will be able to support reviewing translations in Portuguese.

Contact info

• Technical writers interested in working on this project should send an email to seasonofdocs@mautic.org – Please do not contact the mentors directly unless you have a specific question to ask them. Please include links to your technical writing work or portfolio/resumé/CV.

Project Idea 3: Adding more articles that answers FAQs in the knowledge base

Problem

• The Mautic Knowledge Base was released last year and already have a handful of articles that focuses on answering FAQs about Mautic.

• We have an increasing demand to support Mautic users FAQs and we don’t have enough articles that cover a lot of this.

• We need to more support articles in the knowledgebase to assist Mautic users.

How would we measure success?

• Decrease in the number of support issue and an increase in the number of page views by 50%.

• Increased contributions to the Knowledge base from new contributors by 50%.

What skills would a technical writer need to work on this project?

Must have:

• Familiarity with SEO optimization,

• Familiarity with Github (or willingness to work through GitHub tutorials and learn the basics outside of this project).

Mentors

• Favour Kelvin, Education Team Lead, will be the primary mentor for this project and can review pull requests,

• Ruth Cheesley can help with answering questions about Mautic and review pull requests for grammar, content and style.

Contact info

• Technical writers interested in working on this project should send an email to seasonofdocs@mautic.org – Please do not contact the mentors directly unless you have a specific question to ask them. Please include links to your technical writing work or portfolio/resumé/CV.

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!

The Google Season of Docs project is similar to the Google Summer of Code, however it relates to technical writing rather than development, and lasts for three months.

We are excited to introduce the successful applicants who are about to start the community bonding phase where they get to know their mentors, refine their proposals, and get started within the community.

Both will commence working on their projects from 14th September 2020 through to 30th November 2020, with the finalisation period between 3-10 December 2020.

I’m sure you will join me in welcoming our new Mauticians into the community and am looking forward to seeing their work over the coming months!

Swati Thacker – End-User Documentation

I am a senior technical writer with 10 years of experience in translating complex enterprise-level software concepts and technical procedures into simple, easy-to-understand material for end-users.

By leveraging my technical writing experience, I started contributing to the documentation for open-source organizations as part of the Google Season of Docs program since last year. It has been extremely fulfilling to bond with the open-source communities around the world which in turn has helped me expand my knowledge of a variety of domains. You can read my blog here.

Feel free to connect with me on LinkedIn – https://www.linkedin.com/in/swati-thacker/ or on Mautic Slack.

Read Swati’s proposal here (Source is unavailable).

Favour Kelvin – Knowledgebase

I am a software developer and a technical writer who believes in changing the world by translating abstract ideas into comprehensive material is my way of solving complex business problems and being an active player in the dynamics of the company.

I love to code, write, and share knowledge. I am an active open source contributor, helping build technical communities and speak at conferences. I create technical content on myBlog.

Feel free to connect with me via Twitter – https://twitter.com/Fakela6 or on Mautic Slack

Read Favour’s proposal here.

You may have heard of the Google Summer of Code before – this is a similar program but applies specifically to documentation.  The goal of the Google Season of Docs is

To provide a framework for technical writers and Open Source projects to work together towards the common goal of improving an Open Source project’s documentation.

For technical writers who are new to Open Source, this presents an opportunity to make your first contributions and get started with supporting an Open Source project. For technical writers who might already be contributing in Open Source, the program could be a new way of working together, or an opportunity to explore new projects. 

The program brings together technical writers with an Open Source community for a period of a few months, bringing their writing expertise to the project’s documentation while learning about the project, community and technology behind it.

Together, we raise public awareness of Open Source documentation, of technical writing, and of how we can work together to the benefit of the global Open Source community.

The Education Team are excited to be proposing three projects for consideration by the Google Season of Docs team.  All three projects are key to helping our users – whether developers, end-users or marketers – better understand how to work with Mautic.  Read more about the project proposals below, and if you’re interested in learning more do join the Education Team channel on Slack!

Project proposals

Developer documentation

Project name

Create a Developers Portal for the Mautic Community

Project description

Refactor the existing Developer Documentation at https://developer.mautic.org to provide an improved user experience and create a more user-friendly portal for developers.

Background

Mautic is the world’s first Open Source Marketing Automation platform. Launched in 2014, it has grown from strength to strength and has a thriving community of contributors from around the world.  Learn more about Mautic and Marketing Automation. Spin up a sandbox or check out the Github repo.

The Mautic Community Developer Documentation has typically existed in isolation from the end-user documentation and has focused largely on the REST API.  It is currently using Slate and can be found on Github.  

The Product Team would like to implement a more user-friendly approach by creating a developers portal which will signpost people to the relevant resources, whether they need help creating a theme, using the API, or writing their first plugin.

This project will refactor the Developer Documentation to implement these ideas in collaboration with the project mentor and wider Product Team. 

Depending on available skills and time, the project could also involve refactoring the API to facilitate OpenAPI/Swagger based documentation and deploying a new platform for the API documentation.

You can read more about the proposal on the Trello card here.

Related material

• Background on Mautic: https://www.mautic.org 
• Mautic on Github: https://github.com/mautic/mautic
• Developer Documentation: https://developer.mautic.org
• Developer Documentation on Github: https://github.com/mautic/developer-documentation 
• Project proposal on Product Team’s Trello board: https://trello.com/c/1EjNIhBn/27-write-concept-for-developer-docs-revamp 
• OpenAPI Initiative: https://www.openapis.org/
• Swagger: https://swagger.io/  
• Technical writing styleguide: https://contribute.mautic.org/education-team/technical-writing-styleguide

Project Mentors:

Dennis Ameling – Email Slack Forums Github
Norman Pracht – Email Slack Forums Github

End-user documentation

Project name

Review and update the End-User documentation for Mautic

Project description

Review and update existing documentation, including updated instructions and rich media (video tutorials, screen captures etc).

Background

The Mautic Community recently re-platformed the end-user documentation which can be found at https://docs.mautic.org.

The documentation has been somewhat neglected over the past two years, and some resources are out of date, need revising, and could be greatly improved with more effective use of rich media.

The Education Team would like to conduct a thorough review of the documentation and systematically work through a programme of updating and improving the resources available.

When this is complete, there will also be a translation project kicked off to empower community members for whom English is not their first language to translate the documentation into other languages.

You can read more about the proposal on the Trello card here. 

Related material

• Background on Mautic: https://www.mautic.org 
• Mautic on Github: https://github.com/mautic/mautic
• Mautic Documentation: https://docs.mautic.org 
• Docs or KB?: https://docs.google.com/document/d/1HfrTCUE0vsbzYYDQoYmvMcWEAyMVc_tWDbPH-NIAq3s/edit?usp=sharing 
• Technical writing style guide: https://contribute.mautic.org/education-team/technical-writing-styleguide
• Documentation style guide: https://docs.mautic.org/en/home/contributing

Project mentors:

Norman Pracht – Email Slack Forums Github
Ruth Cheesley – Email Slack Forums Github

Knowledgebase

Project name

Create resources for the newly created Mautic Community Knowledgebase

Project description

Write a series of how-to tutorials and guides which will help Mautic users be more effective with setting up, configuring and using the application.

Background

The Mautic Community is in the process of launching a knowledgebase which will live at https://kb.mautic.org. The purpose of the knowledgebase is to be a central repository for tutorials, how-to guides and best practices on topics related to Mautic – whether directly (e.g. how to do things in Mautic) or indirectly (e.g. more general marketing strategies).

See this Trello card for an explanation of what sits in the documentation, and what sits in the knowledgebase.

We have identified a number of tutorials and resources that should be included in the knowledgebase. This project will focus on writing those tutorials and creating supporting content – e.g. videos, images etc – in collaboration with the Education Team.

Related material

• Background on Mautic: https://www.mautic.org 
• Mautic on Github: https://github.com/mautic/mautic
• Mautic Knowledgebase: https://kb.mautic.org 
• Docs or KB?: https://docs.google.com/document/d/1HfrTCUE0vsbzYYDQoYmvMcWEAyMVc_tWDbPH-NIAq3s/edit?usp=sharing 
• Technical writing style guide: https://contribute.mautic.org/education-team/technical-writing-styleguide

Project mentors:

Leon Oltmanns – Email Slack Forums Github
Kevin Rundle – Email Slack Forums Github