Replace on-wiki API documentation with Special:ApiHelp transclusion
Open, NormalPublic

Description

We can replace much on-wiki documentation of API modules and parameters with a transclusion of generated API code \o/. E.g. this wiki edit in replaced a bunch of text in Extension:TextExtracts with {{Special:ApiHelp/query+extracts}}

Directions

  • If the on-wiki text is better, create a phab task in the API's project (plus goodfirstbug and MediaWiki-API ) to improve its PHP help code.
  • If the on-wiki text has version info, don't replace it until we address T90528.

Otherwise replace the on-wiki text with {{Api help| module_name }}.

Related Objects

Spage updated the task description. (Show Details)
Spage raised the priority of this task from to Normal.
Spage added a subscriber: Spage.
Restricted Application added a subscriber: Aklapper. · View Herald TranscriptFeb 12 2015, 1:16 AM
Qgil awarded a token.Feb 12 2015, 11:37 AM

This interesting task makes me wonder whether api.php itself should be also demoted, promoting the API transclusion in wiki pages as the primary means to check API documentation.

Theoretical benefits of this approach:

  • Searchable content.
  • No need to theme api.php, since the docs (being wiki pages) will acquire the theme of the wiki.

If you think this idea is worth discussing further, I can create a new task for it.

This interesting task makes me wonder whether api.php itself should be also demoted, promoting the API transclusion in wiki pages as the primary means to check API documentation.

If the on-wiki doc writers want to avoid mentioning it that's fine with me, but documentation on api.php is IMO too useful to bot and script developers to go away.

Qgil added a comment.Feb 18 2015, 3:57 PM

To be clear, I'm only suggesting that the exact api.php documentation is displayed via transclusion in wiki pages. Same content, only searchable and themed.

Anomie moved this task from Unsorted to Non-Code on the MediaWiki-API board.Feb 19 2015, 6:00 PM

[promote] API transclusion in wiki pages as the primary means to check API documentation.

Theoretical benefits of this approach:

  • Searchable content.
  • No need to theme api.php, since the docs (being wiki pages) will acquire the theme of the wiki.

It's an interesting idea. There are two ways to navigate from transcluded API docs:

  1. The wiki navigation, e.g. the {{API}} TOC template
  2. The "(main | query | extracts)" crumbtrail below the transcluded apihelp-header.

As well as skinning, the generated documentation lacks a TOC and search. These are all doable, but if developers mostly consume the generated doc on-wiki, it reduced the priority of improving the experience of browsing api.php?action=help.

We ought to get metrics of how developers use the API documentation.

jayvdb added a subscriber: jayvdb.Mar 19 2015, 9:38 AM

The generated documentation does not include historical information, and should not replace existing documentation for the core API. It can be a temporary substitute for hand written well written documentation, however the effort should instead be put into building tools which pre-create basic wiki documentation and syncronising the wiki documentation after each release to add/deprecate/remove submodules/parameters/etc that have changed.

Spage updated the task description. (Show Details)Mar 20 2015, 4:10 AM
Spage set Security to None.

The generated documentation does not include historical information.

This is incorrect. Our generated documentation can and will have far better historical coverage than our wiki pages. The wiki has, to my knowledge, never been fragmented by version. Some higher level documentation pages cover older versions in side notes but never for entire chapters, or for API documentation.

Our generated documentation on the other hand has naturally been generated since MediaWiki 1.19. We've had the generator since then. Branches that are even older are no longer supported and no longer have releases that would automatically trigger a documentation build. However we could easily enable a one-time run for legacy branches like 1.18, 1.17 or earlier. As of writing, it already goes back 5 releases.

The generated documentation does not include historical information.

This is incorrect. Our generated documentation can and will have far better historical coverage than our wiki pages.

"can and will have" (future tense and wishful thinking) does not contradict "does not" (present tense).

Regarding versioning, that discussion probably belongs on T90528.

Krinkle added a comment.EditedMar 20 2015, 4:35 AM

This is incorrect. Our generated documentation can and will have far better historical coverage than our wiki pages.

"can and will have" (future tense and wishful thinking) does not contradict "does not" (present tense).

Poor phrasing on my part, but you're missing the rest of my comment. I meant "does and always will have". We've had historical coverage in generated documentation for several years now.

The generated documentation does not include historical information

Thanks for commenting on Task T90528. We should add module version parameters to {{Api help}} in the interim.

and should not replace existing documentation for the core API.

When people have carefully indicated the version of every method and parameter, it's a shame to lose it; I've updated this task's description to discourage this. https://www.mediawiki.org/wiki/Wikibase/API made me add this task, it's a mass of unversioned out-of-date copy-paste that now has many static translations. It's not core API with a lot of history, are you opposed to using {{Api help}} in it?

It can be a temporary substitute for hand written well written documentation, however the effort should instead be put into building tools which pre-create basic wiki documentation and syncronising the wiki documentation after each release to add/deprecate/remove submodules/parameters/etc that have changed.

That sounds like a ton of work. I appreciate volunteers taking it on.
Meanwhile the API to Wikimedia sites evolves constantly, every two weeks. We need to handle latest vs. versions in all generated doc, so I mentioned this in T93026.

We've had historical coverage in generated documentation for several years now.

Do you mean historical coverage in *Doxygen* generated documentation?

If so, how is that relevant to Special:ApiHelp? Is Special:ApiHelp going to load Doxygen?

Dalba added a subscriber: Dalba.Sep 11 2018, 2:54 AM
Dalba awarded a token.Sep 11 2018, 3:49 AM