gwicke wrote on 2014-07-23 00:46:36 (UTC)

I see three different main tasks here:

• a portal that provides a quick overview & introduction
• tutorials on how to achieve common tasks
• structured and detailed API documentation with a sandbox, in sync with the deployed API modules

For the last of these tasks I see advantages in using an existing API spec / documentation tool like Swagger or JSON schema hypermedia (used by Google, Heroku & other large API providers). To keep the API documentation in sync with the current configuration & deployed software version it makes sense to combine documentation with module registration, as is currently done in the PHP API. I am doing the same in restface / rashomon, so far using Swagger docs.

qgil wrote on 2014-07-23 10:58:13 (UTC)

@jgonera, in our last meeting we reached to a "Solomonic compromise: have a button some set of people can push to take mediawiki.org pages and push them to the static site", and we also left some open questions. This is why we agreed to work on a prototype first, in order to unblock documentation and design work while we decide he technical approach. (meeting minutes)

I still have the impression that we have been discussing implementations more than requirements and this is why this task focuses on agreeing on the requirements in the first place. T491 discusses technical solutions to fulfill these requirements.

@GWicke, I have added more detail in the type of "manual content" that editors should be able to create. Your comment made me also think on the need of a common search tool able to scan both the tutorials/showcases and the API docs.

To keep the API documentation in sync with the current configuration & deployed software version it makes sense to combine documentation with module registration, as is currently done in the PHP API.

I see the usefulness of this feature, but... is this within scope of this project? The Developer Hub should offer all the information about an API without being conditioned to the specific configuration of, say mediawiki.org. It is definitely good to able to check what can en.wiki, commons.wiki or my.personal.wiki API offer based on the specific configuration of these wikis, but this is not an information that would fit in the Developer Hub. It could also be that I don't understand what do you mean. :)

gwicke wrote on 2014-07-23 18:48:09 (UTC)

@Qgil: From a user perspective I value documentation that's up to date and matches the API version and enabled modules in a particular wiki. I can't speak to whether this is in scope for this project.

So, in case this is in scope: 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.

qgil wrote on 2014-07-24 15:00:19 (UTC)

In T489#17, @GWicke wrote:

@Qgil: From a user perspective I value documentation that's up to date and matches the API version and enabled modules in a particular wiki. I can't speak to whether this is in scope for this project.

If all Wikimedia projects share the same API version and the same modules enabled, then we should consider matching the docs to that specific configuration, yes.

Something that seems to have worked well for other projects (PHP for example) is to pair authoritative API docs with user comments.

Interesting idea, let's discuss it at T502: Create WMF endpoint for error logging - part 2 (consumer). Links to examples are welcome.

qgil wrote on 2014-07-31 21:29:42 (UTC)

@brainwane, @MSyed, @Anomie, @jgonera, are you happy with the requirements listed above, in the description of the task? If not, please comment / edit. Closing this task will help us kicking other tasks in the right direction.

qgil wrote on 2014-08-21 11:05:12 (UTC)

Let's move forward with these requirements, now documented at https://www.mediawiki.org/wiki/Data_%26_Developer_Hub#Requirements

If you have ideas for improvement, please propose them.

importing issue status