- Published on
- -17 mins read
My Google Season of Docs experience with moja global
- Authors
- Name
- Harsh Mishra
- @harshcasper
I came across Google Season of Docs accidentally last year, through one of my acquaintances, while I was scouring for open source programs to participate in. While it started with a simple message in a blogging community I was a part of, I was left to research and plan for the next steps in the coming weeks. Though I was not selected back then, the whole process of interacting with the maintainers from different communities gave me enough confidence to participate the following year.
Fast forward to 2021, and I was selected as a Google Season of Docs intern with moja global. It was not by accident this time, since I had laid down my plans to improve the documentation for users and developers months before, and I was ready to take up an initiative to deliver it. Moja global has been a participating organization in Google Open source programs. Once Google Season of Docs came in, we submitted a proposal, and luckily we got the funding for the project.
Over the past 6 months, I have been working with the Technical Steering Committee at moja global under the mentorship of Sabita Rao and Sagar Utekar to lay down the revamped documentation, build a content strategy, and deliver a community website for the contributors at moja global. The entire process was coordinated by Dr Andrew O’Reilly-Nugent, Director of Technical Steering Committee at moja global. I worked parallelly with my co-intern, Sarthak Kundra, during the process, and this blog would be documenting my experience and the project report.
Project Goals 🎯
Moja global provides tools for estimating emissions and removals of greenhouse gases (GHG) from the land sector. Full Lands INtegration Tool, also known as FLINT, is the flagship software of moja global and is a platform for data collection, analysis and continuous improvement of greenhouse gas inventories related to land use and land-use change at local, national and global scales. Moving further, the FLINT users are expected to follow the IPCC guidelines to develop increasingly accurate and robust systems for greenhouse gas accounting. In addition to the core FLINT framework, the community has developed a small ecosystem of interrelated tools and platforms, including the FLINT-UI, FLINT-Cloud, FLINT-Reporting and more.
The goal of my project was to develop a content strategy that makes our different documentation types easy to navigate, access and understand. As the community has grown, so has our documentation, some of which remains siloed or inaccessible to end-users and developers who would like to work with us. As the first step, we wanted the documentation across all of our repositories standardized and improved navigation between moja global projects. As an intern, I was primarily focused on auditing the existing user, developer, and policy-focused documentation and developing a content strategy, including case studies, on improving the experience of new users.
 |
|---|
| The user flow map shows the user flow of the documentation from the beginning to the end across the community website. |
Project deliverables 🗓️
During the entire period, I worked on many areas, ranging from documentation development, technical auditing, community management, and website development. During these deliverables, I collaborated with multiple contributors and teams across the moja global, who had helped me gain a solid understanding of the projects they were working on to familiarize myself with the challenges they were facing.
Development of the Community website 🚧
During the Google Season of Docs 2020 project, one of the deliverables were developing the "contributors website". It was supposed to serve as a platform to welcome new contributors at moja global and help them get started with our initiatives. However, to my surprise, no one was using it. It was hosted on a Heroku instance and had virtually no users until we decided to refactor it. Since the original contributor's website was developed using ReactJS and Material UI, we started looking for alternatives and luckily finalized on Docusaurus.
Docusaurus is a static site generator by Facebook (now Meta) built on top of the React ecosystem. The decision was influenced by my familiarity with Docusaurus. Adding to it was Sarthak's experience, who had worked with the Facebook team back during the MLH Fellowship and contributed to Docusaurus. Technically, we were looking for a platform to publish our Markdown-based documentation, which had strong customization capabilities and would allow users to search for the proper documentation.
The first iteration of the new community website is now live at community.moja.global.
We have collaborated with over 30+ contributors through initiatives like Hacktoberfest, who helped deliver various major and minor features during this process. We are also supported by Vercel for all our infrastructure needs across our front-end projects. We've also integrated Algolia search, which comes built-in with Docusaurus, to simplify the search experience for users.
One of our significant initiatives with this milestone was the centralization of documentation. We decided to migrate all our user-facing documentation on the community website while persisting our technical documentation on the Read the Docs website. Through this, we removed the redundancy associated with our documentation. We built a base for our future documentation efforts that help users get started with moja global projects for developers that wish to experiment with FLINT and more.
 |
|---|
| The community website for moja global which hosts the project description, blogs, case studies and tutorials across the community. |
Publishing documentation websites for new projects 📗
A significant reason for the lack of contributions was laid down on poor documentation. It involved projects that had been in development for some time but lacked enough documentation and context for new contributors to get started with. A significant part of the documentation was scattered across Microsoft Word and Google Docs files that needed to be centralized. For this purpose, this milestone focused on developing documentation websites for the new projects under the moja global umbrella.
For this purpose, I worked with the existing Sphinx toolset to build and generate documentation websites. Read the Docs platform was used for publishing these sets of documentation websites while integrating a CI/CD pipeline for continuously building and publishing the websites with each commit. At the end of the Google Season of Docs, we have successfully compiled and published these set of documentation websites for our projects:
- FLINT-UI: docs.moja.global/projects/flint-ui
- GCBM Chile Data Pre-Processing: docs.moja.global/projects/GCBM-Chile-Data-Preprocessing-Tools
- FLINT Reporting: docs.moja.global/projects/flint-reporting
These documentation websites now form a part of the moja global developer documentation and serve as a reference for contributors looking to get started.
Auditing existing documentation across projects ✍️
While starting off with this project, it was essential to keep the maintenance & upgrade of documentation on priority. For this purpose, I worked with community contributors to validate the existing documentation for our developers and have appropriate changes made to them as per the feedback. I also worked on auditing the governance and contributing documentation available on the About moja global repository and migrated them to the Community website for ease of access and usage.
This milestone will continue to be a work in progress as more contributors are onboarded and feedback is received on improving our documentation. The possible areas of work would include:
- Make sure that our existing documentation is readable and usable across all bandwidth.
- Make our existing documentation compliant with the moja global style guide.
- Setting up Vale guides to test and validate documentation continuously on a CI service (GitHub Actions).
While some of these pointers are on the way to being achieved, we would be more than happy to have new contributors contribute to these parts.
Publishing documentation style guide and content strategy 📜
One of the milestones on priority was the development of a documentation style guide for moja global. The style guide aimed to bring standardization across the whole organization and the documentation efforts put into the pipeline right now. The style guide has been heavily inspired by Google's style guide and Red Hat's Documentation guide to ensure best practices are being followed consistently.
On the other hand, the content strategy was focused on the organization administrators, contributors, and maintainers to identify the region where content can be developed and curated for the community outreach. It would also define how the documentation would be structured and laid out, in essence, to make sure it is accessible to all.
The content strategy and the documentation style guide serve moja global contributors and maintainers to follow a consistent framework for all our documentation efforts. We also make sure that documentation efforts are not seasonal and should form a part of our continuous releases and updates to our software projects throughout.
It also ensures that we have an outline of the ways anybody could follow to contribute effectively. In addition to contributing, it also provides insight into our documentation resources and how the users can contribute effectively.
The documentation style guide for moja global can be found here: docs.moja.global/en/latest/DocumentationStyleGuide/index.html
Setting up documentation working group and onboarding new contributors 🎗️
One of the most achievable milestones that I achieved during my internship at moja global was setting up the documentation working group. During a mutual discussion with the maintainers, it was realized that navigating a large and diverse community is challenging, both for coordination and for new participants to find their place. This paved the way for TSC Working Groups to provide a central coordination point for a standard set of topics. Each Working Group will have one or more Coordinators to provide a direct point of contact for the TSC Chair and/or Directors.
Working Groups are about communication rather than accountability and provide a way to build capability through community initiatives. Instead, responsibility is delegated to the individuals responsible for a specific project who choose to report their progress to the Working Group for oversight and collaboration. Such reports allow Working Groups to maintain an overview of ongoing development, published on a moja global website or repository to help the community track who is working on what.
Through my proposal of setting up a documentation working group, we received 170+ applications from open source contributors worldwide. We helped more than 50 contributors to contribute to our documentation projects through initiatives like Hacktoberfest and Outreachy, with over 9 meetups since July. Along with this, we have led a 400% increase in the community size over the past six months, especially in our documentation and outreach.
The success of our documentation working group has paved the way for us to consider setting up different working groups. One of them is the deployment working group responsible for all things DevOps, CI/CD, installation support, release management and reference implementations. The deployment working group would be working with potential Outreachy intern(s) during the December-March round of Outreachy internships.
 |
|---|
| A snap from the Video 11 of the UNFCCC - moja global workshop series where the community outreach and the growth initiatives are talked about. |
Publishing case studies and module documentation 🌞
The case studies served the purpose of communicating the development happening across the community to a broader audience. During my internship, I worked on two case studies for the moja global community: “Powering Deforestation prediction using Artificial Intelligence” and “Benchmarking of FLINT for climate change speedrun”. As of now, one of the case studies for the moja global community has been published here: community.moja.global/case-studies/powering-deforestation-prediction-using-artificial-intelligence.
The second case study is in active development and will be published around December 2021. For module documentation, I collaborated with the moja global volunteers to develop extensive documentation for modules and how a contributor can make a custom module. Modules are the building block of FLINT. These contain the operations, describing the ecological processes and driving the carbon changes in the landscape.
The modules connect with FLINT resources (Pools, Variables, Timing). They have defined operations that reflect processes, such as growth, or events such as harvests or fires, whether natural or human-induced. All of our module documentation is currently hosted on the Google Season of Docs repository and will be further migrated to the Community website. It can be viewed here: github.com/moja-global/Google.Season.of.Documentation/tree/master/modules-development.
 |
|---|
| An example diagram demonstrating how the FLINT manages modules and data. |
Miscellaneous ✨
My miscellaneous contributions to the community revolved around but were not limited to DevOps, community management and helping new contributors onboard. These were out of the scope for my current internship, but they were fun to do nevertheless and helped me navigate the moja global community and understand the ecosystem in a more eased manner.
During this course, I built continuous integration pipelines for various moja global projects using GitHub Actions to improvise build testing for better contributions. Additionally, I was involved in contributions to various projects under the moja global umbrella: FLINT Cloud, FLINT UI, FLINT Reporting, FLINT JSON Editor, and more. I was also involved in helping new contributors get started up with their contributions to the community, primarily through initiatives like Hacktoberfest and Outreachy.
Apart from this, with the help of international collaborators, we led the first attempt for internalization for our documentation. Through Docusaurus’s i18n feature, we migrated some of our Outreachy-specific docs to Spanish to aim for Latin American contributors to contribute to moja global tool-sets. Our Spanish docs are live on the Community website, and we are increasingly looking for new contributors to assist us in our internalization efforts.
 |
|---|
| The GitHub organization page for moja global serves as the starting point for the potential contributors to navigate across the community. |
Challenges faced 📍
While this whole project was challenging, some aspects of it were unforeseen and more challenging. Before Google Season of Docs, I had standard technical writing experience through blog writing and some freelance writing opportunities. I had less to zero experience working on content strategy, outlining the documentation efforts and planning a roadmap to pave the way for extensive and centralized documentation across moja global. With support from mentors, I was able to overcome this challenge with flying colours.
The other challenge was communication. My mentors had full-time commitments, and it was a challenge sometimes to find the time to meet and discuss the next steps. Thanks to the seamless coordinator by Dr Andrew O’Reilly-Nugent, we were able to mitigate the communication barriers and ensured that we communicated our project plan and deliverables well.
Lastly, we spent quite a lot of time validating our documentation experience and user flow. This involved a lot of iterations during the process, getting in touch with the stakeholders and volunteers and making further improvements with the help of the community contributors. This has further helped us develop a solution of segregating the documentation into two different categories and catering to the specific needs of both of them.
Learnings 📚
The Google Season of Docs internship and my participation with moja global was fruitful for me to further develop my technical documentation expertise. I also learnt a great deal about communicating and navigating across a large organization and finding areas to plug in our contributions. I never had the opportunity to work with a large scale open source organization on a more consistent basis. I’m thankful to moja global for providing me with this opportunity.
Working on this project exposed me to a great deal about documentation development, which is not just limited to writing Markdown. The project also offered me multiple opportunities to brush up my existing skills in React, Docusaurus, CI/CD, Python, C++, R, to name a few, while working on the project.
From a software development perspective, I learnt a lot about moja global, MRV (measurement, reporting & verification) software, FLINT and the associated ecosystem. This has further helped me put up code contributions in projects. I will also associate my moa global contributions in and around documentation, DevOps, community management, and outreach.
Apart from the same, I learned a great deal about the communication side of things. Communicating with my mentor and the stakeholders improved my thought process and intuition behind how things work. It also helped me instil a “doer” mentality, where I work fast, fail fast, and iterate quickly. Getting to know fellow LFX and Outreachy interns and the great work they have been doing was also significant for me to understand the ecosystem.
Acknowledgement 🙏
My internship at moja global under the Google Season of Docs was a fruitful experience. I’m grateful to have worked on this project and gotten acquainted with Open source, being in my undergraduate studies itself. Open source has taught me a great deal about many things, and this project has further paved the way for me to cherish my ambitions of contributing to open source communities consistently.
I would like to thank my mentors Dr Andrew O’Reilly-Nugent, Sabita Rao and Sagar Utekar, for being kind and helpful throughout the process. Without their help and impeccable support, it would have been nearly impossible to pull this effort off. I especially cherish my interactions with Dr Andrew as he laid down a concise plan and had a lot of interactions with me that helped me become a better open-source citizen as a whole.
I would also like to thank Sarah Haggarty. She came in as an external contributor and helped me a lot with my documentation reviews, providing feedback on my work and helping me overall shape the documentation flow. It was a pleasure interacting and working with her.
It was also a great experience working with the moja global volunteers: Shubham Karande, Mohammad Warid and Mohit Kumar, whose expertise was invaluable to my efforts. Shubham’s experience of module development and the moja global ecosystem was conducive for my actions. Warid’s expertise in UI/UX was impeccable for us to lay down a documentation outreach and a user flow plan. Mohit did some great work on module development which would soon be incorporated into the Community website.
Lastly, I had the pleasure to work with some of the external contributors throughout this internship. Shloka Gupta arrived in as an early contributor and helped me with documentation reviews and providing necessary feedback. Anirudh Panda helped the documentation team get early feedback on the user flow and provided immediate fixes to improve the documentation.
Sree Vidhya and Debolina Ghatuary, the 2021 Outreachy Interns, did fantastic benchmarking FLINT and helped me create a case study. Julian Cabezas helped me get started with my GCBM Chile Data Pre-Processing project and assisted in publishing the documentation website for the project. Anthony Kwaje, who was the Google season of Docs intern for 2020 and now a maintainer of FLINT Reporting, helped me publish the documentation for Reporting Tool and will now serve as a co-mentor alongside me for Outreachy.
And finally, my co-intern, Sarthak Kundra, has been the rockstar contributor during the entire project. Overall, contributing to this project has been one of the best things to happen to me this year. Working alongside the community and the immense learning associated is something that I shall treasure for years to come.