API:Improving technical documentation

Overview

There have been a number of efforts to improve the technical documentation for the MediaWiki Action API. This page provides information about some of the organized efforts to improve and continue to improve technical documentation.

History

Identifying technical documentation content collections for improvement

In the spring of 2018 the Wikimedia Developer Advocacy team began to identify potential technical documentation content collections associated with Wikimedia projects 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.

The team identified the MediaWiki Action API technical documentation as its focus.

Phases of improvement for MediaWiki Action API technical documentation

Improvements to the technical documentation are ongoing and have gone through several phases

Research and early planning
Phase one: Identify top 20 pages for improvement
Phase two: Outreachy internship focused on improving 20 more pages, create a demo app and tutorial
User feedback survey (See below)

Read Investigate and improve MediaWiki Action API documentation for a detailed account of the technical documentation improvement project from its initial phases until now.

Action API technical documentation survey 2019

Survey design

The survey was a simple google survey, and was a mix of free form and fixed questions about the current technical documentation for MediaWiki action API. All questions were optional. The survey ran for about six weeks in late 2018 - early 2019. Requests for participation were sent to several technical mailing lists and also posted in a banner on MediaWiki Action API pages.

About 50 participants took the survey.

Who took our survey?

Most respondents identified themselves as a Volunteer technical contributor, WMF or Affiliate Staff member or both. A couple of respondents identified themselves as academic researchers.

In order:

A third-party developer for the API, A MediaWiki site administrator who interacts with the API
A MediaWiki site administrator who interacts with the API
A third-party developer for the API
A MediaWiki Action API Developer
Other

Notes: For the most part, there seemed to be little distinction between staff, affiliate or volunteers. Many identified as both, and for purposes of creating technical documentation content, it is likely useful to view this as a unified audience rather than a separate one.

Is Python example code adequate for user needs?

About half of respondents said that the Python examples were adequate for their needs.

About half of respondents said they would prefer examples in additional languages. The most requested languages were (from most to least requested):

PHP
JavaScript
Java and C# (tied)
Others: Ruby, Bash, Perl, Swift, golang

Notes: Based on the responses to this, we should consider providing examples in at least one other language (PHP and JavaScript being the most commonly requested).

The types of technical documentation MediaWiki Action API users most prefer (in order of preference)

Written How-tos and Walkthroughs that show me how to perform a specific task
In-depth explanations of about different features of the MediaWiki Action API
Use cases or recipes for things I can do with the MediaWiki Action API
Simple and minimal reference documentation
Information and resources about how APIs work and how to become an API developer
Video How-tos and Walkthroughs that I can follow along with

In general the users’ experiences of MediaWiki API Documentation

Adequate (21)
Excellent (8)
Poor (5)

The current state of MediaWiki Action API documentation

Note: The answers to this question were entered as free text. The following recommendations are base on trends in the answers.

Recommendations would be to have a process in place for updating documentation and ensuring its accuracy, also to provide multiple, logical avenues for visitors to discover information in the API namespace.

Based on user stories and needs
Taxonomy / hierarchy of information (full sitemap)
Keyword search/discovery

Areas for improvement

Users consistently asked for examples and stories / use cases.

Questions we didn’t ask (which can affect the quality of information and outcomes)

Demographic information: Location, age, gender identity, race/ethnicity, education level, socioeconomic status, etc
Level of experience with API development / Software development in general
Which technical documentation do you use most frequently

Recommendations

Provide more examples and user stories
Create in-depth tutorials / How-tos based on examples and user stories
A variety of ways to search and discover information about the API -- (Think about building an API documentation portal where users can choose how they discover information)
Build trust about the quality of information (timeliness and accuracy)
Provide sample code in at least one or two more programming languages (PHP, JavaScript)
Concentrate on experienced API developers. Point to resources about general API development, but do not create new “educational” content for less experienced developers
Develop some qualitative interview questions for participants who are willing to discuss this further. Use qualitative interviews as an opportunity to generate examples and use cases.