by Gbadebo Bello, Google Season of Docs participant
Google Season of Docs (GSoD) is an annual internship organized by Google. Documentarians and technical writers get the opportunity to contribute to open source documentation as an intern for three months while being supervised and mentored by experienced technical writers at these organizations. The internship is paid, and students get to earn a stipend of about $3000 — $5000 depending on their locations.
I interned at Wikimedia Foundation for three months as a part of GSoD ’20 Internship, and this article summarizes my experience contributing to open source documentation at Wikimedia over the past few months.
- I learned about writing open source documentation.
- I had an amazing time being an intern at the Wikimedia Foundation.
- I got way better at technical writing, improved the onboarding process, and created a review process that will improve the standards of documentation over time.
- GSoD is simply amazing!!!
- And oh, my mentors were my superheroes!
Towards the end of 2019, one of my goals was to write more and explore new ways I could improve my technical and writing abilities. One of the ways I planned on doing this was to gather relevant experience through jobs, internships, and contributing to open source. As of then, I only considered software engineering internships and had written a few articles.
Around February this year, I attended the Open Source Festival, a conference organized by Open Source Community Africa. There was a session about internship opportunities. Edidiong Asikpo spoke about her experience as a GSoD intern at VLC and gave a high-level overview of the program. I got interested and decided to apply.
I eventually decided to apply, and the application phase wasn’t an easy one. There were quite a number of brilliant folks who were applying too. At some point, imposter syndrome set in because I felt I wasn’t good enough and wouldn’t make it.
The application phase was research intensive. There was tons of high-quality documentation already written. My goal was simple: find something that needed to be improved in the documentation, and write a proposal aimed at improving it.
The first thing I noticed was that the documentation was not all in one place. It resides on different wikis and places like GitHub and GitLab. This made me realize that the documentation, even on MediaWiki, didn’t have a consistent format.
Proposing starting templates for genres
Doing more research, I figured that there was a page describing different documentation genres and providing examples of each genre. But something about this page didn’t quite sit right with me. The examples provided for each genre were linked to external documentation which had its own formatting and style of writing. This means that a documentarian who uses the Quick Start Guide (QSA) example to write a QSA document and a documentarian who uses the API example to write an API document will both end up with documentation with different formatting and styles, and both will be WMF’s documentation. I wanted to improve that, so I decided to include the creation of default starting templates for some of these genres in my proposal.
Proposing a standard review process
The inconsistency in formats made me realize that a standard review process was needed. Since none existed, I set out to create one and included it in my proposal.
You can read my proposal here: Improving Wikimedia’s onboarding processes and documentation standards
My proposal was broadly scoped to two things:
- Improving the onboarding processes.
- Improving documentation standards.
The idea was that:
- If all new documents use these templates as a guide, they would find it easier to create documentation.
- If all documentation that is being created/updated use these templates as a guide, there will be consistency across WMF’s documentation formats.
- If all documentation that was created (which is expected to use these templates) undergoes this structured review process, over time, the documentation standards will be greatly improved.
There were a few other things my proposal included which were later de-prioritized. Feel free to go through the proposal to get the full list of things I proposed.
On the 16th of August, I got a very pleasant birthday gift! My proposal got accepted! Yaay!
The internship started off with me learning more about WMF documentation, wiki’s, Wikitext, creating my respective user pages, and learning more about the documentation development processes, styles, formatting guides, etc. It was a lot of information to take in at first, but as time went by, I became used to most of the processes.
GSoD has been running for just two years, and this will be the second year of Season of Docs. I felt there was a need to document my work progress in-depth and to give an insight into why I made certain decisions, my thought process, and how ideas evolved into the work that I did, so I put it upon myself to document this as a weekly Phabricator task. Each task discussed the work that I did, my research, and the conclusion drawn for that week. This will be particularly useful to future GSoD interns and mentors or anyone who is curious enough to want to get an in-depth insight into what I worked on.
Creating templates for different genres
There are quite a lot of genres that documentation can be written on at WMF, I couldn’t create templates for all genres as I had just three months. I prioritized three genres and set out to create templates for each of them.
The templates I created are:
- Quick Start Guides Documentation Template
- Walkthoughs, how-tos, and tutorials templates
- Library Documentation Template
- API Documentation Template
The Library and API genres were previously categorized as one genre (API & SDK genre), but SDKs are too verbose to be categorized as a genre; they are toolkits that consist of several tools (APIs, libraries, code samples, documentation, processes, etc). Some of these toolkits are genres on their own (i.e APIs), of which documentation is a part of the toolkit of an SDK. So we decided to re-scope this into just the library and API genres, and I created templates for those.
These templates were created so someone writing documentation for the first time can find it easy to use. The templates outline who can use and what the documentation can be used for and provide an explanation of some concepts where necessary.
Go through each task to find out what I worked on for each genre.
Creating the review process
The review process I created was in three steps:
- Prototype/Self Review
- Technical Review
- Non-technical Review
The first step involves doing a copyedit pass by the author of the documentation, then getting a subject-matter expert to do a technical review, after which a reviewer does a non-technical review and asserts that this documentation conforms with the style and formatting guides.
The progress of this documentation is tracked using a documentation review workboard which was created specifically for this review process.
The review process is explained in much more detail in this document.
To read about how I came about this document, the research and the discussion that lead to its creation, go through this task, and pay attention to the discussion in the comments.
The best part of GSoD?
The mentors! I was privileged to have been mentored by Sarah R. Rodlund and Alexandra Paskulin. They were the kind of mentors you would always wish for, again and again. They were always thoughtful in their suggestions, mentoring, and were super empathetic when necessary!
Learning can be fun, but being guided by a mentor makes your learning easier and more structured. Having someone who can provide timely and appropriate answers to your questions is a wonderful experience, I was fortunate to get that from Sarah and Alex. I had an amazing time working with them.
Anyone who is a technical writer should definitely consider writing in the open source space. GSoD gives you the opportunity to do just that! It creates an avenue for contributing to open source in an uncommon way while improving your technical writing skills under the mentorship of more experienced writers.
Learn more about the GSoD program here.
Got questions? Feel free to leave a comment or reach out to me on Twitter.
About this post
A version of this post originally appeared on Gbadebo Bello’s blog.
Featured image credit: Macro photo of the keyboard included with Dolch’s PAC 65 Mobile Sniffer Network Analyzer Computer (with added CODE key sourced from a TA Royal Beta 8050 Typewriter), Joseph L Ridgway II, CC BY-SA 3.0