Status

• Write draft
• Tech writer review
• Team review

Context

The documentation for AQS 1.0 exists in two places:

• pages on Wikitech with tutorials, guides, and links to the reference documentation (See this list of links.)
• reference documentation in the form of OpenAPI specs served using Swagger UI through the RESTBase API docs

There is no user-focused entry point for all AQS 1.0 API docs.

For the new AQS 2.0 services, we have the opportunity to reconsider where we store this documentation. This decision record describes two options we considered and makes a recommendation.

Scope

This decision only covers user documentation for AQS (tutorials, guides, and reference docs). Maintainer docs (deployment guides, data processes, etc.) for AQS will remain on Wikitech as is standard practice for Wikimedia infrastructure documentation.

Goals

• Users can easily discover and share AQS APIs through a single entry point
• Users can find information they need within the docs
• Contributors can easily maintain the docs

Options considered

1. Wiki pages with standalone API specs (AQS 1.0 model)

In this approach, landing pages, tutorials, and guides are stored on wiki pages. These wiki pages link to the OpenAPI specs which are served separately through doc.wikimedia.org.

User experience

Users arrive at an on-wiki landing page where they can navigate to other wiki pages with more information about the API or use case they're interested in. They are then directed off the wiki to view the API spec on a different site.

Advantages

• Storing docs on wiki makes editing easy and fast.
• Search is integrated with wiki search. For example, searching for "monthly pageview count" on Wikitech brings you to the Pageviews API docs.

Disadvantages

• The wiki pages and the API spec look and feel like different sites. There is no navigation to help users move between them.
• No obvious fit with either Wikitech, MediaWiki.org, or Meta-Wiki:
  • AQS 1.0 user docs live on Wikitech. However, since Wikitech is typically focused on WMF infrastructure docs, Wikitech isn't necessarily a good fit since these are public APIs that may be of interest to a wide community of users, developers, and researchers. In addition, docs on Wikitech cannot benefit from translation.
  • Since these APIs are specific to Wikimedia infrastructure and aren't part of the MediaWiki platform, these docs are also not a good fit for MediaWiki.org.
  • Typically, Meta-Wiki is the best place for widely relevant, translated documentation, but Meta doesn't typically contain docs that are as technical as these docs.

2. Unified static site

In this approach, we would create a standalone static website that incorporates tutorials, guides, and API specs.

User experience

Users arrive at a site dedicated to AQS API docs. They can navigate between tutorials, guides, and API specs without leaving the site. For example, see the Blubber docs site recently set up by the Tech Docs team.

Advantages

• All docs have a consistent look and feel.
• Docs are presented through a cohesive navigation structure.
• Using the static site generator Vitepress allows us to use a modern theme while creating minimal maintenance burden.
• We can integrate API spec elements with tutorials, providing functionality to test API requests within the flow of a tutorial.
• By displaying API specs through a static site, we can easily switch the tool we use to display the specs if a better option becomes available.

Disadvantages

• Only minimal translation features are currently available for Vitepress, although coupling with the tool used by Codex means that, if they develop an integration with translatewiki, we can make use of it in our docs.
• Edits to the documentation would need to be submitted through our code review system. This is easy and convenient for developers but not for all users of the docs.
• Because the docs are not part of a wiki, they are not as easy to discover as if they were stored on wiki.

Proposal

To provide the best experience for users of the APIs, we recommend option 2: unified static site. OpenAPI specs are powerful tools, but they don't integrate well with MediaWiki at this time. By using a static site for the docs, we can present the docs in a polished and cohesive way. We can also make the sandbox feature of the API specs an integrated part of the docs, making it easier for users to get started with the APIs.

Although there are many static site generators available, we recommend using Vitepress for consistency with the Codex docs. Sharing a tool across documentation projects reduces overall maintenance burden and creates a consistent user experience.

Although contributing to the docs will not be as easy on a static site as it would be on a wiki, the process to add a new AQS API to the docs will be significantly simpler since you will only need to add a few pages to the static site instead of setting up the wiki content and the API spec separately.

To make sure that the static docs site is discoverable from the wikis, we can create wiki pages that appear in search results and direct users to the docs site.

Decision

Use approach 2, and build a unified static site for the AQS user documentation.

Consequences

The Tech Docs team will create a Vitepress site on GitLab to host the AQS user documentation. Tech Docs will design an information architecture, create the content, and set up the build pipelines to publish the site to doc.wikimedia.org. The Tech Docs team will also set up wiki pages to help users discover the docs using on-wiki search.

Everyone on Data Products will have edit access to the repository to contribute to the site and the documentation, and Tech Docs will own critical maintenance tasks for the site going forward, including critical software updates and major bugs. Teams creating new AQS APIs will be responsible for adding docs to the site, with Tech Docs available to review and provide feedback.

As a result of this approach, users will have a cohesive experience for reading the docs and experimenting with the APIs.