Page MenuHomePhabricator

Possibility to pair API documentation with user comments
Open, LowPublic

Description

Should the possibility to pair API documentation with user comments become a requirement for this project? Sounds like a good idea, also very much in line with the MediaWiki/Wikimedia practice tradition of having discussion pages next to content pages.

In T489#17, @GWicke wrote:

Something that seems to have worked well for other projects (PHP for example) is to pair authoritative API docs with user comments. Maybe we could focus the on-wiki effort on the comment aspect, with a single location for comments per API entry point and major version. This way authoritative docs / a per-wiki sandbox front-end can include or link to comments for each entry point, while also reflecting the actual version & modules in a particular installation.

URLs of examples are welcome.

Details

Reference
fl502

Related Objects

Event Timeline

flimport raised the priority of this task from to Normal.Sep 12 2014, 1:44 AM
flimport added a project: Web-APIs-Hub.
flimport set Reference to fl502.

gwicke wrote on 2014-07-24 15:40:15 (UTC)

PHP docs: http://php.net/manual/en/function.substr.php

qgil wrote on 2014-07-31 21:45:25 (UTC)

At T491#11 I'm proposing to find a way to publish API docs in MediaWiki pages, which would allow us to just use the related Talk pages (with Flow).

Qgil lowered the priority of this task from Normal to Low.Oct 22 2014, 6:20 PM
In T322#3826, @flimport wrote:

qgil wrote on 2014-07-31 21:45:25 (UTC)
At T491#11 I'm proposing to find a way to publish API docs in MediaWiki pages, which would allow us to just use the related Talk pages (with Flow).

As I've been wading through all of the discussion in the various Phab tickets as soon as I saw this requirement I immediately thought, "wait, MediaWiki Talk pages provide this already". Therefore, my opinion for API presentation is in agreement with qgil here in that figuring out how to use MediaWiki would be beneficial.

Wmat removed a subscriber: Wmat.Dec 5 2014, 3:08 AM
Qgil added a subscriber: Krinkle.EditedMar 17 2015, 10:27 AM

For the record:

  • discussion pages (T322)

Enabling talk pages for each documentation page will be a chaos. I've seen this happen in various other projects. Never worked. Proxy discussion through a single talk page, or refer to an issue tracker.

The main use case is: "I have a question using this API, where can I ask?". The reply might become a useful part of the documentation, as a simple reply or as a patch/diff to the existing documentation.

If discussion wiki pages are not a good solution for this, then we need a good solution.

Also @GWicke says it is a good idea while @Krinkle thinks it never works. We need a commonly agreed opinion. :)

Qgil added a subscriber: GWicke.
Qgil added a comment.Jun 11 2015, 9:27 AM

This is not a critical feature for T101441, so I will detach it from our short term plans.