Page MenuHomePhabricator

Improve and update: https://www.mediawiki.org/wiki/API:Data_formats
Open, NormalPublic

Description

https://www.mediawiki.org/wiki/API:Data_formats is one of the most popular pages in the API namespace on MediaWiki. The page contains valuable information about Data Formats for the MediaWiki Action API.

Recommendations:

  • Make this page more of a reference doc than a user guide. The information here should be quickly and easily accessible to readers. Much of the contextual information is unnecessary for application developers who visit the page for simple information.
  • Some of the content that is currently available on this page may be better suited for the API: FAQ page.

Event Timeline

srodlund created this task.Sep 19 2018, 9:35 PM
srodlund triaged this task as Normal priority.
srodlund created this object with edit policy "Custom Policy".
Legoktm changed the edit policy from "Custom Policy" to "All Users".Sep 19 2018, 9:52 PM
Anomie moved this task from Unsorted to Non-Code on the MediaWiki-API board.Sep 20 2018, 1:56 PM

Make this page more of a reference doc than a user guide. The information here should be quickly and easily accessible to readers. Much of the contextual information is unnecessary for application developers who visit the page for simple information.

OTOH, making it a reference doc might leave it no purpose that's not already served by https://www.mediawiki.org/w/api.php#main/datatypes.

srodlund added a comment.EditedSep 20 2018, 10:48 PM

@Anomie that is a really good point. It makes me wonder what purpose https://www.mediawiki.org/wiki/API:Data_formats serves, if we already have a reference to point to? I wonder if we just point to https://www.mediawiki.org/w/api.php#main/datatypes from the FAQ page and/or elsewhere, could we retire this page?

That said, my inclination is almost always to reduce the number of pages with duplicate information. If there is a good reason to keep it, we should.

As I've said elsewhere, I like to think of the auto-generated documentation as the reference card and the on-wiki documentation as the user guide. If there's no need for user guide content for something, then there may not need to be an on-wiki page at all (or just a stub).