I changed the Grouping operations section of the OAD style guide in the hope of making it a bit clearer. Feedback and edits welcome!

Despite our style guide's broad recommendation against it, I (very briefly) looked into changelog automation. The most popular open-source tools for this purpose seem to be: git-cliff, conventional-changelog, and git-chglog. These tools generate changelog content based on git metadata. I tested their outputs using one of my own projects. My main conclusions are:

• None of the tools provided output that I'd recommend using as changelog content without any edits. However, all the tools generated outputs that I could use as a starting point for my own changelog edits.
• The quality of the output depended on the quality of commit messages and the use of semantic versioning for all the tools. As expected, main inconsistencies in the output were related to the commit messages, not the tools themselves.
• git-cliff provided output that would require the least effort to turn into a changelog that meets our style guide recommendations. Its Keep a Changelog template worked well, and I could use the output as a starting point for my own changelog edits.
• conventional-changelog provided output that was the most complete, but would require significant editing and didn't follow Keep a Changelog recommendations. I imagine that if the commit messages in my project's repository adhered to the Conventional Commit format, the output would be much better. However, some edits would still be necessary.
• git-chglog produced output that wasn't as useful as the other tools. In my project, its Keep a Changelog template didn't work very well, likely due to inconsistent commit messages.

The OAD example now includes:

• a recommendation for messages about endpoint deprecations
• a recommendation for documenting enum values

First draft of the example is now available for review in this GitLab repository. Note that GitLab doesn't feature a preview tool for OpenAPI descriptions. You can preview the JSON or the YAML file in a local or web viewer of your choice.

The main content and structure of the example OAD is done but I'm still improving summaries and descriptions and making small fixes based on feedback I already received. I also need to write the accompanying README, which will explain some of the choices I made, and highlight some open questions, proposals, and potential issues.

This is still in progress and will continue next week.

The main focus of this work is now on:

• the list of recommended and required OAD fields (Google Sheet, restricted access)
• example/test OAD work (T410087: Create example/test OAD)

Currently working on the initial version of the OAD in the YAML format. I'm planning to follow the pattern of pet shop API examples unless someone suggests a better alternative.

I've added a short section about internationalization to the changelog style guide. It links to relevant internationalization resources and highlights key points to keep in mind when preparing on-wiki changelogs for translation.

In T338554#11269581, @HCoplin-WMF wrote:

Just calling out that we are close to moving on this: https://phabricator.wikimedia.org/T396807

I assume that when the ticket linked there is complete, we can call this done as well. Is that accurate or are there additional needs?

These changes are now live and this task is done.

All the changes necessary to bring Analytics API docs into alignment with standard documentation patterns have been applied and are ready for review in this merge request on GitLab (alongside a few technical updates to documentation dependencies).

I have now created the first proposal for the list of required and recommended OAD fields. The proposal is based on OpenAPI specification (OAS) v. 3.0.0 and includes fields required by that version. It has now been shared for review.

In T405038#11231305, @HCoplin-WMF wrote:

@KBach that's a fair question. Especially since we are planning to include the date as an extension property, it doesn't necessarily have to be within the endpoint description for consumers of the raw spec to get that information either. I wonder where would get the data from if we are injecting it into the explorer without it being part of the spec though?

In T405038#11207030, @HCoplin-WMF wrote:

For the description changes, I would expect them to be the last line of the description with two new lines of whitespace, which follows the pattern set by RESTBase originally. A suggestion for the actual text to add to the description might be:

Normal endpoint description.

WARNING: This endpoint is deprecated. It will be removed on or around {Month} DD, YYYY.

Where the second sentence is only included if a date is provided. I'm also not totally sold on the "WARNING" label, but thought it might draw more attention. Would be curious for @KBach to weigh in.

All work planned for this task is now complete and summarized in task description, in the Outcomes section. API documentation work continues in T405569.

First drafts of the OAD style guide and the API changelog style guide are now published on mediawiki.org. Work on these documents will continue in T405571: Improve OAD style guide based on feedback and emerging requirements and T405573: Improve API changelog style guide based on feedback and emerging requirements respectively.

A proposal for the standard API changelog structure and format is now in review. Currently focusing on the API documentation content strategy and the plans for Q2.

First draft of the OAD style guide has been shared for review. I'll be improving the document based on feedback over the coming weeks. Now focusing on the API changelog and documentation content strategy.

Work on the OAD style guide was delayed and is still continuing. Currently planning to have the first draft ready for review by end of next week (12 September).

I have now finished constructing the API patterns catalog and am analyzing it as a basis for the OAD style guide. Wikimedia Analytics API and Wikimedia Enterprise API are not part of the catalog and will be used to evaluate the style guide recommendations.

I'm cataloging current API reference documentation patterns for analysis (already done with MediaWiki REST API, moving on to RESTbase). I'm planning to start formulating style guide entries based on these patterns in the middle of next week.

We've made a recommendation for the location of the new API sandbox and documentation.

We are still selecting the location for the new documentation, currently in the process of filling out the decision matrix (restricted access) and discussing different benefits and trade-offs.

Completed so far:

• Initial research into API documentation features and technical architectures - results shared with the Technical Documentation Team
• Identification of core deliverables, their requirements, priorities, and dependencies

This project has now been completed.

The main project documentation page is now in review. I'm still making minor changes in the other docs (README, reference), and in the tools themselves. I'm planning to finalize this project next week.

The linter rule reference is now on wiki, awaiting a few final modifications. I'll move it to its final location when the other documentation (still in progress but almost done) is ready.

I've been away most of the week so there hasn't been much progress in this task. Work on the documentation is still ongoing.

• I merged and deployed the final bug fix in the web app.
• I researched the possibility of replicating the linter CI pipeline for projects in Gerrit. We now have a general idea of how to achieve it, but will not implement it as part of this task.
• Linter rule reference documentation is now undergoing a review. I will publish it on mediawiki.org when it's ready.
• Other documentation is still in progress.

• I deployed a new version of the wiki linter to https://techdoc-linter.toolforge.org/. This version features UI improvements, new usage instructions, and a few bug fixes.
• One final bug fix is ready for review in this MR in GitLab.
• I'm still working on the documentation.

Main tests are done and bug fixes are ready for review. I will now work on minor UI improvements in the web app, continue verifying the fixed rules, and write documentation.

I'm still in the process of testing the tools:

• Almost done testing the wiki linter. Still need to identify a root cause for one bug.
• Started testing the repositories. Here I'm focusing on making improvements to style rules with particularly high false positive rates.

• First prototype of the wiki linter is now live on Toolforge.
• Main set of style rules in the quickstart repository is now complete.
• We are now ready to start testing the tools in real projects and on existing documentation.