I just saw your changes to API:Opensearch. As I understand it, the preference is to have both the manual API documentation as well as the automatic API documentation. The manual documentation provides additional, version-specific information so that people can target their bots/utilities against multiple versions. In the wild, outside of Wikimedia sites, it's not uncommon to see MediaWiki versions as low as 1.20 or so, so it's important to have historical information readily available.
Topic on User talk:SSethi (WMF)
Thanks for your comment! We are trying to make the documentation of most popular action pages more consistent by following this template API:Documentation for all, embed the API docs as provided via Special:ApiHelp transclusion, add sample code where necessary, etc. We are changing the format only, and not removing any useful information. The deprecated parameters if any and included in the automatic API documentation, would still be shown as it is with the transclusion.
What about information about which version of MediaWiki parameters were introduced in, deprecated in, and probably most importantly, deleted in? I didn't see anything like that in the version of the page after the template was applied. Take, for example, the profile parameter of OpenSearch. If I'm designing a bot, and I'm targetting 1.25 and above, I need to know that that parameter was only introduced in 1.28, and that I can't use it (at least not without some kind of version check). On the previous version of the OpenSearch page, it was obvious at a glance. Now, it's nowhere to be found (unless I go through the page history, which isn't a tremendously useful way to find information). Similarly, if an older parameter is deleted, I need to be able to see that it's deleted at a glance, not read through a bunch of existing parameters to determine that the one I'm using is no longer there. That's why we had the API Param template in the first place, was to document all this kind of information over and above the auto-documentation.
I just had a thought on this: I'm guessing that the motivation for the change is to have the live docs being the main source of information, and that makes sense. What about putting your template first, but then keeping the ApiParam stuff underneath and renaming the section to "Parameter History" or something along those lines? That would accomplish both goals of having the live docs be the easiest to find, while the historical information remains readily available to bot developers.
You are right, and it's my fault that I didn't consider to include in the documentation template the version information about MediaWiki parameters. Thank you for sharing about this :) The parameter section was added back to the Search page by a user, and taking your suggestions into account, I ended up making modifications to their edits and then for now presenting only that information which is not covered in the automated docs here: API:Search#Parameter history. I will investigate how I can use ApiParam to display it in the way it is in the current revision.
I also saw there is a related task on Phab: T90528. I will try to figure out if it is feasible to include this information in the live docs.
That looks good. I really like your colour coding for the version information. That makes the information even more readable than it was previously. I wouldn't necessarily say you should constrain yourself to using ApiParam specifically if you have something that's better formatted. Even as one of its primary designers, I'll admit that it's very plain. Design aesthetics aren't my strong suit. :) However, you should definitely look at it at least in terms of the information it was designed to track, to figure out what kinds of details people want to have captured when it comes to parameter documentation.
On a side-note, one of the frequent issues I've seen come up among designers is that there's little documentation about what output to expect from each API module, beyond one or two examples which don't always cover every possible output. I realize that that's a lot of work for something as large as the API, but I think it's something a lot of developers would probably appreciate. Just something to think about for the future.
:) Another thought that I've -- how about we show Parameter History in a changelog format:
- v1.16: Introdced srinfo, srprop
- v1.17: Introduced nearmatch, score, titlesnippet, sectiontitle, etc.
- v1.22: Deprecated srbackend
And, then the question would be how important is to show default values and other miscellaneous info that we manually show in the parameter section? Do you've any thoughts on this?
For me, I think that would work. I can't speak for other developers. Default values and the like are certainly nice to have if they've changed over time, but in my experience, that's fairly rare in the API.