Google Season of Docs Project Report — Wikimedia Foundation

TL;DR

• I learned about writing open-source documentation.
• I had an amazing time being an Intern at 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!!

Genesis

Towards the end of last year/early this year, 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 Internships, contributing to Open Source, and Jobs. As of then, I only considered Software Engineering Internships and had written a few articles.

Revelation

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.

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 at a reputable organization of choice for 3 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.

Getting In

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 were tons of documentation already written and were of high quality. My goal was simple, find something that needed to be improved in these documentations, and write a proposal aimed at improving it.

The first thing I noticed was that these documentations were not all in one place, they had documentation that resides on places like GitHub and GitLab. This made me realize that these documentations, even the ones that resided 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 linking to external documentation which had their own formatting and style of writing. This means a documentarian who uses the Quick Start Guide(QSA) example to write a QSA documentation, and a documentarian who uses the API example to write an API documentation will both end up with documentation of different formatting and styles which will both be WMFs 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 documentarians 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 WMFs documentation formats.
• If every 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!

Getting Started

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 2 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 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 down 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 alike, 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 3 months. I prioritized 3 genres and set out to create templates for each of them.

The templates I created are:

1. Quick Start Guides Documentation Template
2. Walkthoughs, how-tos and tutorials templates
3. Library Documentation Template
4. API Documentation Template

The Library and API genre were previously categorized as one genre(API & SDK genre), but SDK’s 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 Library and API genres and created templates for those.

These templates were created so someone writing documentation for the first time can find it easy to use, it stated who can use and what the documentation can be used for at the top and provided an explanation of some concepts where necessary.

Go through each task here to find out what I worked on for each of this genre.

Creating the review process

The review process I created was in 3 steps:

• Prototype/Self Review
• Technical Review
• Non-technical Review

The first step involves doing a copy edit 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 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.

Final words

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.

If you found this article Interesting, please clap! I’d love the attention!

Got questions? Feel free to leave a comment or reach out to me on twitter.