Page MenuHomePhabricator

Possibility to pair API documentation with user comments
Closed, DeclinedPublic


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.


TitleReferenceAuthorSource BranchDest Branch
Add tests that assert evaluator no longer returns whitespace outputsrepos/abstract-wiki/wikifunctions/function-evaluator!196ecarggrace/T322345/add-whitespace-error-testsmain
Switch Python WASM to RustPython/wasmedge.repos/abstract-wiki/wikifunctions/function-evaluator!90apineapine-wasmedge-pythonmain
Do not suggest images that are already on the pagerepos/structured-data/image-suggestions!12cparleT322669T311289
Use a builder format for the allpages generatorrepos/mwbot-rs/mwbot!9legoktmgenerator-redomain
wmf: Use binary distribution of terraformrepos/releng/gitlab-terraform-images!9dduvallreview/lets-use-binary-distwmf/stable
Refactor to use WMF gitlab-terraform-images/blubber/kokkurirepos/releng/gitlab-cloud-runner!16dduvallreview/use-wmf-imagemain
Add repos/releng/gitlab-terraform-images to trusted runnersrepos/releng/gitlab-trusted-runner!5dduvallreview/add-gitlab-terraform-imagesmain
Customize query in GitLab

Related Objects

Event Timeline

flimport raised the priority of this task from to Medium.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:

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 Medium 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.

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. :)

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

Aklapper subscribed.

The Web-APIs-Hub project is dead hence mass-declining its tasks to reflect reality. It might be superseded by a Developer Portal in the future.