AQS 2.0 is a project to replace the analytics-aqs service (referred to in this task as AQS 1.0) with a set of new microservices. In 2022 and 2023, we completed foundational work to set up API documentation tooling in the new services and make the API specs available. In 2024, we are focusing on making these docs available to users and deprecating the AQS 1.0 docs. The 2024 work is led by @apaskulin and @KBach.
Visit the new AQS user docs site: doc.wikimedia.org/analytics-api
Terms
- User documentation: documents needed by end users of the API, including the API reference, tutorials, and explanations
- API reference documentation: In contrast to other types of user documentation like tutorials and explanations, the API reference is the detailed contract describing all the functionality of the API, including endpoints, parameters, error codes, and response schema. For AQS 2.0, the API reference documentation takes the form of machine-readable OpenAPI specifications.
- Maintainer documentation: documents needed by maintainers of the API, including development and testing guides, deployment guides, monitoring docs, and service-level objectives
Goals
- Make it easier for development teams to maintain the user docs compared with the AQS 1.0 user documentation.
- Reference docs are maintained alongside the code they describe.
- Create a self-service process for development teams to create user docs for new AQS services and endpoints
- Create a single entry point for all AQS user docs for ease of sharing
- Create user documentation for AQS services that is:
- Findable: Users can discover the docs from commonly-used entry points and can find information they need within the docs
- In-site navigation and search; on-wiki links redirected to new site
- Useable: Information is organized based on user needs and tasks; users can get started using the API as quickly as possible
- User research showed users could effectively get started and perform tasks using the site.
- Accurate: Information is trustworthy and up to date
- Tutorial code samples are tested as part of the site's CI.
- Reference docs are maintained alongside the code they describe.
- Consistent: Common behavior across APIs is documented the same way, limited the learning curve for users
- API specs updated to conform with published style guide
- Findable: Users can discover the docs from commonly-used entry points and can find information they need within the docs
Scope (April - June 2024)
In scope:
- User docs for the original set of AQS 2.0 APIs (Device, Geo, Media, Page, Edit, and Editor Analytics)
- Instructions for creating user docs for a new AQS API
Out of scope:
- Work on maintainer docs on Wikitech is tracked separately in T356693: [SPRINT 09][SDS 2.6.4] AQS 2: Complete AQS 2.0 maintainer docs to do’s
- Commons Analytics or other new AQS services will be handled as pilots for the new self-serve user docs creation process
Project plan (April - June 2024)
Subtasks to be created. Note that phases with the same numeral can proceed in parallel.
- Phase 0: Project kickoff
- Tech writers project kickoff discussion and alignment
- Publish project plan to parent task
- Sync with the dev team
- Phase 1: Decide on approach, toolset, and style
- Phase 2a: Design information architecture
- Phase 2b: Set up scaffolding for new docs
- Phase 3: Create site prototype and share for early feedback
- Phase 4a: Update API specs to match style guide
- Phase 4b: Write and publish tutorials and explanations
- T364799: Write access policy for AQS docs
- T365436: Add examples for all APIs
- T365437: Write AQS tutorials
- T366973: Write getting started guide for AQS docs
- T366974: Write stability policy for AQS docs
- T366975: Write clients page for AQS docs
- T366976: Write troubleshooting guide for AQS docs
- T366977: Write concept pages for AQS docs
- T367473: Write changelog page for AQS docs
- T367474: Write contributing guide for AQS docs
- T367475: Write homepage for AQS docs
- Phase 5a: Get feedback
- Phase 5b: Write and publish style guide and contributing guidelines
- T367965: Write AQS API spec style guide
- Add process for new site to Wikitech
- Phase 5c: Redirect old AQS docs to new docs, and add discovery pathways
- Phase 6: Post-launch
- T368967: Page view statistics for the AQS docs site
- Share via the analytics mailing list (post)
- Stretch goal
Investigate Scalar as an OpenAPI spec viewermoved to Tech Docs Team's backlog as T369598
Scope (2022-2023)
- Test and update the 1.0 spec to ensure accuracy https://github.com/wikimedia/restbase/pull/1322
- add a changelog to AQS/Devices_Analytics to capture the error response type change caught in T337511 (edit)
- Find docs for which wikis are supported
- Development guide (Published to Wikitech)
- Testing guide
- Monitoring documentation
- Decide on tooling (Published to Wikitech)
- Demo test environment
- Demo swag to the team
- Document swag and RapiDoc integration and implement skeleton
- Team tests and evaluates swag and RapiDoc
- Implement API doc tooling in all services
- T317802: AQS 2.0: Pageviews: Create OpenAPI Spec
- T317723: AQS 2.0: Mediarequests: Create OpenAPI Spec
- T317721: AQS 2.0: Unique Devices: Create OpenAPI Spec
- T327838: AQS 2.0: Editor Analytics: Create OpenAPI Spec
- T327839: AQS 2.0: Edit Analytics: Create OpenAPI Spec
- T331348: AQS 2.0: Geo Analytics: Create OpenAPI Spec
- Add make docs command in all services
- T343268: Serve API spec endpoints for AQS services publicly
- Create a demo app on Toolforge to serve the specs with a UI
- Investigate translation support T322456: Investigate translation for OpenAPI specs
- Plan for deployment T324861: Plan deployment of API docs
Future work
Documentation work to consider outside the scope of this task:
- Internationalization (See T322456: Investigate translation for OpenAPI specs)
Appendix: AQS documentation structure as of 2024-01-24
Wikitech
- Data_Engineering/Systems/AQS
- overview of AQS
- links to user documentation wiki pages (Analytics/AQS/Pageviews, etc.)
- maintainer documentation for AQS 1.0
- AQS_2.0
- maintainer documentation for AQS 2.0
- Analytics/AQS/Pageviews
- Analytics/AQS/Devices Analytics
- Analytics/AQS/Wikistats 2
- Analytics/AQS/Mediarequests
- Analytics/AQS/Editors by country
- user documentation (quickstart, guides, examples)
- link to API reference documentation (OpenAPI spec)
- link to detailed dataset documentation
- changelog
wikimedia.org/api/rest_v1 (RESTBase OpenAPI spec)
- API reference documentation in the form of API specs (specific endpoints, parameters, error codes, response schemas, etc.)
- all AQS services merged into one spec along with other RESTBase APIs
- access policy details
- link to versioning policy