Google Season of Docs‘22— Month 1

Through this blog, I will share my experience of getting started with Google Season of Docs as a Technical Writer for moja global.
Though the title says Month 1, the preparation and work started much before. I have been contributing to moja global since December 2021.

I am primarily inspired by moja global’s initiative to combat the climate crisis using technology. I can’t thank my mentors and community enough for the hand-holding and constant assistance.

Week 1

• Restructured the technical documentation to ensure easy navigation and readability.
• Upgrade the theme from ReadTheDocs to Furo. The Furo theme has an amazing UI!
• The moja global project is visited and interacted with by people from various technical and non-technical backgrounds, hence in addition to creating issues on Github, it is necessary to ensure that the users can directly submit feedback from the documentation website. The Microsoft and Async API documentation were some references I used. This week was about exploring how the feedback feature could possibly be integrated into the Sphinx documentation website. The main functionality required was to obtain feedback from the Sphinx website and log in to a database
• FLINT or the Full Lands Integration Tool is open-source software that helps users accurately and affordably estimate greenhouse gas emissions and removals from forestry, agriculture and other land uses (AFOLU). GCBM is an adaptation of the FLINT in Canada. The source documentation of GCBM is written in C++, hence Doxygen was one of the best choices to create the documentation.

Week 2

• I continued working on the feedback funnel. I learned that raw HTML can be embedded in Sphinx, which meant I could use an approach similar to how forms are handled in traditional web development projects. Some approaches I explored were :
  1. Use of Google Sheets API, the authentication procedure involved in this method was complex
  2. Use of a database such as Firebase, seemed like an overkill for the functionality required
  3. Use of third-party integrations with Google Sheets like Sheety , might be an option we will consider later
• The best solution I found was to Integrate Sphinx with Google Sheets using Google Apps Script.
  The way I implemented it :
  1️⃣ Create a simple feedback form with a text input and a submit button in Sphinx. Sphinx supports embedding raw HTML, and including custom CSS and JS. Hence, it is possible to handle events and design beautiful DOM elements.
  2️⃣ Write JS to handle the input submission event. The data is POSTed to Google Apps Script
  3️⃣Write a Script on Google Apps Script to handle the POST request which contains the form data
  This method is an efficient and quick way to set up a feedback funnel without the hassle of having to maintain a separate backend, Google Sheets does the magic!
  Here is a glimpse of how the feedback funnel works : https://user-images.githubusercontent.com/53875297/170833853-353cfe31-2612-4c17-8951-ade7b2ab8ada.mp4
• The initial plan was to use Doxygen to generate the source C++ documentation, and use Breathe to show it on a Sphinx-based theme. The way this works is that Doxygen generates the documentation in the form of XML documents, Breathe then parses these XML documents, extracts the required content, and enables display on Sphinx. Essentially, Breathe is a bridge between Doxygen and Sphinx

                      Doxygen 🌉 Sphinx
                            Breathe

Proposed workflow for the documentation

Week 3

• Generating Sphinx documentation using Breathe wasn’t as easy as I thought, for each file, I repeatedly had to use the same Breathe directives, from an overall UI/UX perspective, I felt there is scope for improvement. So I pivoted to trying out some CSS customisation on the documentation generated by Doxygen, my mentors suggested the use of this theme : https://jaideep777.github.io/Plant-FATE/html/index.html

Updated workflow for documentation

• It indeed was an amazing template, this theme had a clear demarcation of the Namespaces, .cpp files, .h (header files), there were inheritance diagrams showing the various classes and their relationships etc. This seemed to work best for our use case. Once we zeroed on using this theme, I continued writing the source documentation. I followed writing a brief description for each class file, and for each function, a description of it in detail
• The PR for the feedback funnel was merged this week. There was a feedback box for every section, which had theory, and for pages that included installation information, each page had a feedback form.
• To ensure that the documentation followed a consistent writing style, my mentors suggested the use of Vale. Since it had to be integrated with the CI, vale-action was the perfect choice. On a PR, vale-action runs and reports the warnings, errors and suggestions it finds. The Google Style Guide is followed in our organisation, hence that was given as the reference input style. However, this did not work as well as expected.

Week 4

• I continued working on writing the source documentation for GCBM, I won’t deny, but this is a pretty complex task, understanding how all the pieces are put together and what each function does, Phew, it’s challenging, but I’m up for it :)
• The vale-action was not the best fit in our case, hence we decided to move to a simpler alternative presently, that corrects spellings on pre-commit. I learned the concept of a pre-commit hooks and integrated codespell on pre-commit. codespell checks for commonly used spellings and corrects them

Work for the next months

• Complete the source documentation for GCBM
• Write some case studies and create tutorials
• Create documentation guides for GCBM Belize and Columbia.

Key Takeaways and Learnings

• Technical Learnings
  - Documentation generators like Sphinx, Doxygen
  - Navigating through large-codebases
  - A deeper dive into Github Actions
  - Hooks used on various events (I primarily worked with pre-commit hooks)
  - Utilities to lint documentation like vale, codespell
  - Integrating Google Apps Script with webapps, creating libraries and exploring the various possibilities.
• Non-technical learnings
  - Learning to communicate effectively on Slack
  - Drafting messages which convey exactly what I want to say
  - Understand the working of open source communities
  - Help other contributors get started with their open source journey

Stay tuned for updates in the further months !