## Status
- [x] 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](https://wikitech.wikimedia.org/wiki/Data_Engineering/Systems/AQS#Hosted_API).)
- reference documentation in the form of OpenAPI specs served using Swagger UI through the [RESTBase API docs](https://wikimedia.org/api/rest_v1/#/)
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](https://doc.wikimedia.org/releng/blubber/) 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](https://vitepress.dev/) allows us to use a modern theme that matches the [Codex docs site](https://doc.wikimedia.org/codex/latest/), 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](https://vitepress.dev/guide/i18n) 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](https://vitepress.dev/) and its default theme for consistency with the Codex docs. Sharing a tool and theme across documentation projects reduces overall maintenance burden and creates a consistent 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
[To be completed following team review]
## Consequences
[To be completed following team review]