Fixing The Docs is a Group Effort
Inside the year-long effort to improve MediaWiki API technical documentation.
By Sarah Rodlund and Srishti Sethi
This article is cross-posted by Sarah Rodlund. Don’t forget to drop by her page and give her a clap!
In this blog post, we will share highlights of a year-long effort to investigate and improve MediaWiki Action API documentation on MediaWiki.org. We believe that the model we followed will be helpful to project communities inside and outside of Wikimedia bring life to outdated technical docs in their projects!
We need better documentation! The internet depends on it!
Wikimedia technical projects rely on the goodwill and brilliant, tireless efforts of a robust technical community, many of whom are volunteers. Many of them contribute to MediaWiki, the software that some of the most beloved corners of the internet are built on. See: Wikipedia, Wikimedia Commons, etc.
Because they are working in distributed ways, members of the Wikimedia technical community rely heavily on technical documentation to help them to participate in projects, maintain software and tools, and to innovate. The technical documentation is written by many different people. It is written with the best intentions, but it is often disorganized, incomplete, inaccurate or out-of-date.
Outdated or missing technical documentation makes it difficult or impossible for many folks to contribute to Wikimedia projects.
Focusing on the needs of the developer community
In the spring of 2018, the Wikimedia Developer Advocacy team, which focuses on helping the developer community build and scale successful projects using Wikimedia technology, started to identify potential technical documentation content collections that could benefit from concentrated improvement efforts.
The idea was to pick a well-trafficked content collection, to develop, apply, and evaluate a number of strategies for improvement, and to use what we learn to build model processes for improving technical documentation across Wikimedia projects.
Preliminary research and planning
Srishti Sethi, Developer Advocate, and Sarah R. Rodlund, Technical Writer, kicked-off an ambitious technical documentation project to research and improve the state of the MediaWiki Action API docs.
Together, we examined well over 100 wiki pages from the API namespace on Mediawiki.org as well as the existing API documentation related tickets in Phabricator, the bug and issue tracker the Wikimedia technical community uses to collaborate.
We identified two main problems areas within the MediaWiki Action API technical documentation:
- At the time, the API:Main_page functioned as the main landing page for visitors who were searching for information about the MediaWiki Action API, but it was not serving its purpose as a hub for Action APIs. The page was confusing to navigate; it contained a hodgepodge of information about APIs in general, and essential information about the capabilities and audience of the API was missing.
- The documentation of each of the modules supported by the API was inconsistent across the API namespace. Some documentation pages contained sample code; some didn’t; some had auto-generated docs embedded on them; some didn’t, etc.
Phase 1: Kicking off the improvements
With so many documentation pages to review and improve and limited bandwidth to do so, we decided our efforts would be best spent concentrating on the most popular pages first.
We performed a massviews analysis under the Category:MediaWiki_Action_API and identified the top 20 most viewed pages. These included the homepage, topic pages (e.g. informational pages: Errors and warnings, FAQ, Etiquette, etc.), and module pages.
A number of contributions took place during the first phase:
- Improved the homepage (API:Main page) and re-organized the supported modules in the navigation template (Template:API) to better communicate what is possible with the MediaWiki Action API.
- Developed API:Documentation_template that all module pages could adhere to.
- Overhauled API:Tutorial targeted at new contributors and developed a demo app tutorial API:Nearby_places_viewer to demonstrate the use of Action API and be used as a reference for building more demo app tutorials.
- Set up a Mediawiki API demos Github repository to collect code snippets and demo apps created during this process on MediaWiki.org, which received much love from new contributors ❤
Phase 2: Google Summer of Code and Outreachy interns take the project to the next level
After improving the top 20 most viewed pages, we had a better understanding of the work that needed to be done. We promoted mentorship projects that focused around improving the next set of pages and developing sample code in different programming languages through Wikimedia’s participation in two of the outreach programs: Google Summer of Code and Outreachy.
Through outreach programs like these, we are able to work one-on-one with individuals who are interested in learning more about technology and participating in Wikimedia’s open-source projects. Outreach participants and dedicated volunteers generously share their knowledge and time to make the technical documentation across projects more functional.
Thanks in particular to:
- Marty Hernandez Avedon (T204612)
- Jerop Brenda (T215682)
- Jay Prakash (T215681)
- Zainab Abubakar (T236786)
Each of these individuals made a significant contribution to this documentation project ❤
Jay Prakash’s Sample Code Gadget
As part of their Google Summer of Code project, Jay Prakash developed a gadget that enables the embedding of a tabbed window on all pages in the API namespace on MediaWiki.org and allows switching between tabs to view sample code in different programming languages. This dramatically changed the functionality of the MediaWiki Action API module pages.
Additional research and improvements
- To gather feedback on the ongoing improvements, we developed a MediaWiki:Gadget-userfeedback.js (Phab: T195119). This user feedback gadget gives visitors an opportunity to share on-the-spot feedback about technical documentation. It is currently enabled in the API and Help namespace on MediaWiki.org and Wikitech, respectively. Visitors can see it in action on any of the pages in these namespaces; scroll to the bottom of the page to see a user feedback form like this.
- We also conducted a technical documentation survey to understand the needs of the technical contributors and to establish our priorities for the next phases.
- As a Wikimedia Hackathon project, we developed a showcase of interactive demos apps built using the MediaWiki Action API that you can play with on Wikimedia Toolforge: https://tools.wmflabs.org/apps-gallery/ (see screenshot below).
Lessons we learned
Over the course of the year, we learned so much. Here are a few highlights.
Be grateful for the existing documentation
It’s very easy to look at community-sourced technical documentation and say, “This is a mess.” We have heard this or shades of this from many people in our movement.
Documentation can be frustrating, but it is the result of the loving work of hundreds of volunteers over the years. The mess exists because a lot of people cared enough to try to communicate their knowledge with others, so they can also contribute.
Even a huge mess can be cleaned up using small, meaningful steps
When we started, all we knew is that MediaWiki Action API documentation was a mess — a big one.
We knew it would be a challenge, but after we did our research, we knew it was not an intractable problem. We first focused on a small segment of the documentation — the most visited pages. This was strategic. We knew this would have the most immediate meaningful impact on visitors. We also knew that it would draw more attention to the project, and hopefully, more folks would want to contribute.
You can’t solve for; you need to solve with
Our basic goal for this project was to solve a problem for our technical community and to make it easier for them to use tools that are important to them.
We learned that we couldn’t solve that problem without the help of the community we wanted to help. Once the project took off, our roles were supportive.
As a team of two, we were able to do the preliminary research and planning and provide guidance and expertise, but members of the technical community did a large part of the work. They took the project on, raised questions, solved problems, and created innovations — like the sample code gadget — that will make technical documentation better across Wikimedia projects.
Future directions
So far, we’ve improved around 100 pages in the MediaWiki Action API technical content collection. Watch here for more: https://phabricator.wikimedia.org/T198916.
Our goal is to identify more technical content collections and to apply our methods and learnings to make additional improvements. It is our hope to foster a community of documentarians within the technical community, to improve technical documentation across projects and to support improvements to technical resources for everyone making contributions to Wikimedia projects.
This article is cross-posted by Sarah Rodlund. Don’t forget to drop by her page and give her a clap!
