👩🏾‍🎤hello

My Google Season of Docs(GSOD) experience in a nutshell

. ☕  5 mins read

A GSOD-2020 project report prepared by Jacqueline Binya on 29 November 2020

During the Google Season of Docs (GSOD) 2020, I contributed to the Creative Commons’ WordPress base theme usage guide project.

Creative Commons (CC) Base is a universal WordPress Theme used to build front facing websites for CC. My role as a technical writer was to create community facing documentation for the CC Base theme collaboratively with the engineering team.

This involved creating the content for the docs, creating all illustrative media and also building the site used to host the documentation.

Planning - Community Bonding phase

During the GSOD - Community Bonding phase, I had a meeting with my mentor Hugo Solar in which we strategized on how to effectively build the docs: this included refining and polishing up the project’s objectives and action plan based off the proposal I submitted for my GSOD application and also, establishing a workflow for doc development.

We decided to:

  • Create a Google Doc to persist all the draft content which was accessible to all the team members
  • Create a tracker document to manage and evaluate progress.
  • I prepared wireframes for the docs site.
  • We chose a documentation tool we wanted to use to build the docs site.

We Create the Docs - Content Creation

To build the docs site we used JamDocs a Gridsome theme. We had to adapt the theme: JamDocs, so as to make it meet our own specific needs, this involved overhauling the theme’s default styles and also, changing the functionality of some of the features in the theme.

With regards to the doc development process: Its important to mention that the GSOD spans for 13 weeks and in the proposal each week’s expected deliverables are outlined. So to develop the docs for each week, we would start off with a team meeting to discuss the content for the section we were working on that particular week, then next I would create draft content in a Google Doc during the course of the week. My mentors: Hugo Solar and Timid Robot Zehta, would then review the draft and suggest changes asynchronously, then I would then implement feedback gathered. Once the draft content was approved I then would migrate it to the docs site.

The mentors were readily available to answer questions on various communication channels and promptly gave me the assistance I required.

The codebase for the documentation of CC Base theme is available in the creative-commons/creativecommons-base repository on Github, in a git branch called docs. All content related to the documentation is persisted in that branch.

Tech Stack

As it was mentioned we used Gridsome a static generator for Vuejs. We chose Gridsome because:

  • We wanted to lower the barrier of entry to contributing:

    • Gridsome/Vuejs community is very active, help is but a click away.
    • The Gridsome official documentation is very resourceful and well maintained.

  • Gridsome offers support for Markdown (a markup language) through plugins, all the content pages in the site are written using Markdown.

  • Time Constraint: This project is a short running project which has to be completed in a 3 month period. Through the use of JamDocs, a Gridsome templating theme as well various plugins it was easy and fast to get started. We were able to add more functionality to the theme with minimal effort.

  • Ease of integrating CC Vocabulary with Gridsome: it is a requirement that the general aesthetics of all front facing Creative Commons applications is derived from the CC Vocabulary Design System. Major cons for using a design system include ensuring uniformity in design for all front facing CC products.

Tools Used

  • Figma: Figma was used to make assets(banners, logos and diagrams) in the theme. The illustrative media was created with accessibility in mind and all the topography used in the illustrative assets was derived from the CC Vocabulary.

  • VokoScreenNG: an open source screencast recording tool used to record all the screen cast demos available in the docs site.

  • ShortCut: an open source video editing tool.

Please find listed below the pull requests (PRs) I opened during GSOD:

  1. Initial Project setup
  2. Adds linter and code formatter
  3. Adds content for the overview section
  4. Updates the Overview Section
  5. Adds the getting started section
  6. Adds the usage guide section
  7. Clean Sidebar
  8. Fix favicon
  9. Copy to Clipboard
  10. Fix logo
  11. Customization content
  12. Adds copy to the clipboard feature
  13. Advanced Customizations section
  14. Updates content for the update theme section
  15. Adds contributing content
  16. Fix scroll markdown
  17. Fixes hamburger in mobile and removes redundant styles
  18. Removes the static folder its unused
  19. Updates the site name and homepage content

CC Base docs - The Outcome

The docs are live 🎉 and are found this url: https://cc-wp-theme-base.netlify.app/

My lessons

  • Working as part of a remotely distributed team I learned a lot about best practices for effective async communication.
  • I also learned about etiquette of participating in online meetings: this was especially important skill to learn in 2020 as remote work has since become the norm.
  • I was writing prior to gsod but contributing to an org like creative commons in a team with senior developers there was a lot of transfer or knowledge as consequence my writing has immensely improved.
  • I learned a new technology: WordPress. This was a challenging feat but I am happy that I persisted and grateful for all the help I got from my team.