Wikimedia Technical Documentation Team/API documentation strategy

This document proposes goals for Wikimedia API technical documentation, and an action plan to accomplish them. It represents the Wikimedia Technical Documentation team's recommendations for how to present Wikimedia API docs if we have common infrastructure developed as part of WE5.

Goals

These goals reflect our plans to address the opportunities identified during the API listening tour and in the API strategy (restricted Google doc link). They also align with broader Tech Docs goals: "Documentation effectively meets users’ information needs" and "Build the culture of documentation".

API docs help developers discover and decide between APIs. API docs entry points include paths for beginners and experts, and paths for known-item searching vs. exploring. Our API docs orient developers and help them decide which API to use. In some cases, this means obscuring complexity and providing opinionated guidance, in other cases, it means providing better tools and UIs for navigating that complexity. API docs are easy to find, navigate, and use. Developers can find and navigate API docs regardless of the platform or entry point where they start their info-seeking journey. Instead of each API doc collection being its own silo, the docs all include "escape hatches" that support horizontal navigation across pages and collections. Consistent content patterns help developers find API information when and where they expect it, and make information easier to comprehend. API docs are accurate and relevant. Wherever possible, we generate API reference documentation via OpenAPI descriptions so that doc content is sourced from a single, reliable source of truth. We increasingly move towards publishing example code or tutorials via checked-in code, so they can be validated against actual API behavior. Templates based on content types help ensure that docs cover only relevant information, are audience-appropriate, and that each doc collection includes the minimum viable set of documentation. API documentation is extensible and collaboratively maintained. The Wikimedia API ecosystem includes multiple types of APIs, created and maintained by both staff and volunteers, by separate teams and orgs, across multiple platforms. To effectively manage technical documentation at this scale, we must empower all Wikimedians to create and manage API docs in alignment with the best practices and standard content patterns. This requires community outreach, self-service tools, clear guidelines, and processes to support (and require) documentation updates that maintain doc consistency and quality, regardless of how the API offerings may evolve.

Scope for FY25-26

For a list of all APIs included as in-scope for documentation standardization work this fiscal year, see Wikimedia Technical Documentation Team/API documentation strategy/Gaps.

The scope of implementing standard doc patterns for these docs does NOT include migrating all the content to one single platform. The only docs that we must migrate are those on the existing API portal.

Strategies

Overview and quick links for the following sections:

Strategy	Objectives	Timeline FY25/26
Define and implement API documentation patterns	Define and publish API documentation patterns.	Q1
	Improve and implement API documentation patterns.	Q2 - Q4 (+ongoing)
Design and implement a new API docs discovery experience	Design and test new API docs portal.	Q3-Q4? (many dependencies)
	Migrate existing API portal content.	Q4?
	Launch new API docs portal.	likely next fiscal year

Define and implement API documentation patterns

Q1 Objective: Define and publish API documentation patterns

This objective started in Q1 with research and discovery of desired API doc features, best practices, and current state of our docs. Its primary deliverables are this strategy doc, and the following documentation patterns:

What pattern to define	Link to key artifact	Lead	Tracking
OpenAPI description (OAD) style guide	OAD style guide	Kamil	T398348
Collection-level information architecture	Documentation/API documentation	Tricia	T403864
API documentation templates/guides	Documentation/API documentation	Tricia	T403864

Q2 Objective: Improve and implement documentation patterns in API doc collections

Tentatively Q2-Q4 +ongoing

This objective creates the building blocks for our future, more holistic doc experience. To start bringing API doc collections into alignment with our standard patterns, we must continue to iterate on the style guides and recommendations we defined in Q1, exploring how they may need to change as we start applying them to real doc collections. The implementation process starts with exploratory work to define the processes, scope of work, and tech writer support required by each API's maintainers to evolve their docs towards the desired experience.

Q2 Workstream	Status	Lead	Tracking
Tech docs support for implementing standard API changelogs	Research & discovery	Kamil	T405573
Tech docs support for implementing OAD-based reference documentation	Research & discovery	Kamil	T405571
Tech docs support for implementing standard API documentation patterns	Research & discovery	Tricia	T401711
Implement doc patterns per API	Planning	Tricia	T405969

🚩 Dependencies:

In order to begin work on a given API doc collection, technical writers need an API maintainer/team who can commit the time necessary to work with us to implement the patterns for their API docs. The time required may vary by API: see the API documentation strategy gap analysis. At minimum, we expect this work to require 1-2 hours per week of time from a developer (subject matter expert), and commitment from the team to do a docs sprint that will be coordinated by a tech writer in collaboration with the SME's support.
For APIs that are in-scope for standardization using OpenAPI spec: any work to finalize that API's doc contents is partially blocked until the API has generated reference docs in a format that supports linking to documentation for specific endpoints. Tutorials and other non-reference docs contain links to specific endpoint documentation, so if the location of that is changing, the content work can't be considered "done".
Some APIs are only documented on the API portal, so any work to bring their docs into alignment with the standard patterns will mean either migrating content to another location (where?) or knowingly adding/revising content on a platform that we know is planned for deprecation (not great).

Design and implement a new API docs portal

Objective: Design and test new API docs portal

Started Q1 but pushed to Q3-Q4 (and still uncertain due to dependencies)

🚩 Dependencies:

Some, but not all, of this work depends on us first implementing patterns within individual API doc collections. For example, we need each API to have at least a standardized landing page that we can link to from the new portal.
In order for an API docs portal UX to feel consistent, each included API's docs should be using the standard patterns, BUT…it may not be possible to achieve that for all the APIs that should be included in the portal. If only a subset of API doc collections are standardized this fiscal year, we would either need to consider this objective blocked, OR we'd need a way to still include non-standardized but important API docs in the new portal. This may detract from the overall cohesion of the UX, but we can't exclude the Action API and other APIs that are part of the Wikimedia ecosystem just because they may not (yet) follow our preferred doc patterns.
For APIs that only have docs on the existing API Portal, this work is blocked until we have moved those docs to their new, preferred location (because the new API docs portal must link to that).

Work likely required:

Choose platform for new cross-collection entry point (portal)
Design IA to support navigation to individual API landing pages from portal (T399765)
- Determine how to include navigation to new sandbox/explorer UI
- Add consistent links between collections and docs
Ensure consistent links between API sandboxes/explorer and non-reference docs
Create wrapper content? Header / footer, or on-wiki template that provides continuous context and escape hatch across all API doc collections
Create / update content for portal
Write and revise API overview and disambiguation content (guidance and well-lit paths)
Content audit of all API policy docs: must be deduplicated and single-sourced
Do user testing and get feedback; iterate on design and content
Design portal maintenance processes

Objective: Migrate existing API portal content

Tentatively planned for Q3-Q4?

Moving the documentation that is currently only the API portal is necessary to avoid duplication, enable discovery, and prevent confusion. The new API docs portal will replace the existing API portal with a more sustainable solution.

⚠️ We need to determine how content migration of docs currently on the API portal intersects with the engineering work and plans to deprecate the API portal. If eng is delayed in work to reroute the APIs that are using the underlying gateway infrastructure, can we still move the doc content whenever we want?

🚩 Dependency alert: Before we can migrate existing API portal content, we need to know the desired location for that content. This dependency also impacts the work to bring the API doc collections on the existing API portal into alignment with the new standard patterns.

Objective: Launch new API docs portal

Tentatively: Q1 FY26-27 but very uncertain

Alongside a formal launch and all it entails for comms etc, tech writers would need to:

Revise existing discovery tools (Developer Portal) and pages to link to new API docs experience
Publish documentation and a contributing guide for the new API docs portal itself

Key concepts

This section explains some key terms used in the API documentation strategy, with the goal of creating shared understanding so we can communicate effectively.

API sandbox

A web-based interactive tool that supports making calls to an API (or its test equivalent). May include other interactive features. Often (but not always) includes some API reference documentation, or links to that documentation, so that users have the necessary context and explanation for endpoint behavior.

Often, an API sandbox corresponds to one API. But, since we're talking about implementing a sandbox that supports toggling between different APIs (see: https://phabricator.wikimedia.org/T400174), Tricia has started using the term "uber-sandbox" to refer to that and differentiate it from a single-API sandbox. We can come up with a different term if needed :-)

Collection

A group of technical documentation pages that have some meaningful relationship to one another. Different types of collections can capture different types of relationships between pages. The most common type of collection is pages about the same product or software ("Action API collection", "Toolforge collection"). We can also imagine collections that gather pages of the same content type (like tutorials, reference, or landing pages); or pages that support a given developer task or user journey ("New developers collection" or "Content reuser collection").

When we say API docs or API docs collection, we mean: a set of tech docs for one API. At minimum, this usually includes overviews, how-to guides, tutorials, and reference docs (whether published as sandbox or another format). The Analytics API doc site is a good example of a full collection of API docs.

Content pattern

A generic term for guidelines that define requirements for technical content, and how that content should be structured. We apply content patterns to both collections and to pages to make the developer experience more consistent and the docs more usable:

At the collection level, content patterns are represented as information architecture (IA).
At the page level, content patterns are represented as style guides and templates.

Content types

Also called: doc types

A best practice in technical writing that defines four key kinds of documentation, each of which correspond to a different user need: tutorials, how-to guides, reference and explanation. For Wikimedia tech docs, we also define portal and landing pages as standard entry point content types. See Documentation/Toolkit.

Entry point

Not the same as "API endpoint"

In the technical documentation context, this means a single location where a developer can go and, regardless of their goal or use case, be guided to information that meets their needs. For Wikimedia tech docs, we usually define two key content types for entry points:

Portal: An entry point that spans multiple collections of documentation. It supports high-level navigation and helps users narrow their search by providing a "well-lit path" to more specific information. May be a full website, like the API portal or the Developer Portal, but can also just be a page (example, example).
Landing page: An entry point for a single collection] of documentation. The purpose of an API docs landing page is to provide entry into that API’s docs (all of them – not just the reference docs or sandbox). Example landing pages: API:Action_API, Analytics API.

Whether an API docs entry point is cross-collection or for a single API, it should include paths for beginners and experts, and paths for known-item searching vs. exploring. Entry points usually represent the root or top-level node(s) in an information architecture.

Information architecture

Information architecture (IA) is a type of content pattern. It defines the structure and relationships between pages, collections, and across collections. IA defines the types of technical documents required to complete a collection, how those documents should be related to one another, and how we expect users to navigate to, from, and across collections and pages. Consistent IA across collections makes the developer experience more consistent and the docs more usable.

Page

A discrete unit of technical documentation, often used interchangeably with "doc". Tech docs can be published as HTML pages, markdown files, or as wiki pages, so we usually prefer "doc" as the more generic term. Usually we don't use "page" when referring to documentation embedded in an interactive UI like an API sandbox, because the presentation of information in that context is dynamic. Individual endpoint descriptions are "documentation" but they aren't really "pages".

Reference documentation

A technical documentation content type that contains technical facts that a user needs in order to use a technology. For APIs, reference documentation must include endpoint descriptions, parameters, and request & response examples. API docs may also include other types of reference content, for example: non-endpoint specific error codes. API reference documentation is often surfaced within an API sandbox, on a page (or set of pages), or both.

Style guide

A style guide is a type of content pattern. It expresses how information should be presented and formatted on a page, or within a specific type of document. Consistent use of style across pages makes it easier to comprehend the different types of information being presented. Style guides for tech docs may overlap with coding conventions, since code comments are considered technical documentation.

Template

A template is a type of content pattern. It expresses which information should be included or excluded on a page, (or within a specific type of document), and how that content should be structured. Consistent use of templates to structure information on pages makes it easier to find and comprehend the different types of information being presented.