API:Improving technical documentation

From mediawiki.org

Overview[edit]

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[edit]

Identifying technical documentation content collections for improvement[edit]

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[edit]

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

  1. Research and early planning
  2. Phase one: Identify top 20 pages for improvement
  3. Phase two: Outreachy internship focused on improving 20 more pages, create a demo app and tutorial
  4. 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[edit]

Survey design[edit]

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?[edit]

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?[edit]

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)[edit]

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

In general the users’ experiences of MediaWiki API Documentation[edit]

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

The current state of MediaWiki Action API documentation[edit]

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[edit]

Users consistently asked for examples and stories / use cases.

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

  • 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[edit]

  • 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.

Next Steps[edit]