Create an information architecture for organizing the AQS user documentation on a dedicated static site

• Create proposal (private Google Doc until tech writer review is complete)
• Tech writer review
• Publish to task

Team review and user feedback will be done after implementing a prototype

AQS docs site information architecture

Guiding principles

• Present the APIs as a cohesive system instead of as separate APIs, minimizing duplication of information shared between APIs.
• Present information in terms of things users are interested in. Avoid non-obvious terms, such as “Geo”.

Meta

• Site title: Wikimedia Analytics API
• URL: doc.wikimedia.org/generated-data-platform/aqs/analytics-api
• Redirect: doc.wikimedia.org/analytics-api redirects to homepage

Due to limitations with GitLab docpub, docs must be published to doc.wikimedia.org using the path of the repository in GitLab. Although we would prefer to publish the docs site to doc.wikimedia.org/analytics-api, this isn't possible with docpub's currently functionality. Instead, the docs will need to be published to doc.wikimedia.org/generated-data-platform/aqs/analytics-api, mirroring their location in GitLab alongside other AQS repositories. To mitigate this complexity, we'll set up a redirect from doc.wikimedia.org/analytics-api to doc.wikimedia.org/generated-data-platform/aqs/analytics-api so the shorter URL can be used to easily share the docs.

Sidebar

Items in italics are not links and used only to structure the sidebar. Sections will not be collapsed. See the following sections for details about each page.

• Documentation
  • Getting started
  • Access policy
  • Stability policy
  • Clients
  • Troubleshooting
  • Changelog
• Concepts
  • Page views
  • Unique devices
  • Bytes changed
  • Country data
• Examples
  • Page metrics
  • Project metrics
• Tutorials
  • Compare page views
  • [Other tutorial topic TBD]
• API reference
  • Devices
  • Edits
  • Editors
  • Media files
  • Pages
• Contributing

Sections

Homepage

The homepage introduces the API and provide links to other pages on the site. The call to action links to the Getting started page. In the future, we could add a showcase of featured apps that use the API.

Documentation

General API topics and explanations

• Getting started: Introduces Wikimedia and the concept of projects, describes how to make your first request, and links to other APIs that users may need in their app (for example, to fetch content)
• Access policy: Includes all the information users need to access the API in accordance with Wikimedia policies, including User-Agent instructions, link to terms, link to privacy policy, data licensing, and rate limits. This page also includes a note that these datasets can also be downloaded via dumps.wikimedia.org.
• Stability policy: Versioning and breaking change policy
• Clients: List of client libraries with the APIs they support
• Troubleshooting: Common pitfalls and gotchas with the data and the APIs
• Changelog: Combined changelog for all APIs, updated manually when changes are made to the API. Based on my experience with other Wikimedia APIs, I assume that changes to the API will be fairly infrequent, so a manual process will be easier than an automated system that needs to be maintaiend. We will need to document this process in the maintainer docs as well.

Concepts

These pages serve as landing pages for information about how we define key concepts in the data. This information lives primarily in the Research namespace on Meta-Wiki. We don't want to duplicate that information too much, but we can use these pages to summarize the basic concepts and link out to wiki pages for more details.

• Page views: Explain how page views are defined
• Unique devices: Explain how unique devices are defined
• Bytes changed: Explain net vs absolute byte difference
• Country data: Explain privacy considerations and limitations

Examples

These pages include URLs with common use cases to serve as helpful quickstarts for working with the API, as well as inspiration for the kinds of requests users can make. These pages will be organized by scope: requests related to a specific page or file and requests related to a project as a whole.

• Page metrics: Example: Get a pageview count timeseries of en.wikipedia's article Albert Einstein for the month of October 2015
• Project metrics: Example: Get a daily pageview count timeseries of all projects for the month of October 2015

Tutorials

Step-by-step guides to working with the APIs, with code samples.

• Compare the pageviews of two articles: Based on the original AQS tutorial https://gist.github.com/marcelrf/49738d14116fd547fe6d, using Pywikibot to fetch article information
• Another tutorial topic TBD

API reference

API reference docs using OpenAPI specs

• Devices
• Edits
• Editors (includes Geo)
• Media files
• Pages

Contributing

The contributing page includes information about how to contribute to the site, how to add an API, and how to write API docs that conform with the style of the site.