Talk:Web APIs hub/Archive 1

General comments

There's an Engineering Community Team responsible for this, is this their proposal?

mediawiki.org is the hub of which you speak, and already has a Developer hub page and even a How to contribute for "developers beyond just coding MediaWiki", so it's unclear how this proposal differs from "do a better job on mw.org." Creating a new dev.wikimedia.org seems like a non-starter, the way to improve a web site is rarely to start another one. Any proposal for a new site must comprehensively enumerate how it relates to existing wikis and what will become of their overlapping pages, and the bar is set high, appropriately.

It should be easier to present resources on mediawiki.org. In particular I think the external auto-generated documentation should be static read-only pages on mw.org; I'm sure there have been bugs and proposals for this. Especially the (new and cool) CSS "living style guide" for the desktop site needs to appear on this wiki in the developer's current choice of skin and Beta features.

The proposal mentions "be a friendly and inviting sandbox environment" but doesn't propose anything concrete. Again thinking about CSS, we could do more to let people make UX experiments; or is hacking around in a browser's developer console and then with <span>s and <div>s in a test wiki page enough of a sandbox?

-- S Page (WMF) (talk) 04:14, 7 January 2014 (UTC)

I just learned about this page thanks to a link from [[[BarebonesMediaWiki]]. I need some time to digest all this. I really appreciate getting help to improve our developer documentation, but I agree with S that we should discuss the plan before concluding that we need a microsite from developers. Even the concept of "Wikimedia Developer Hub" deserves some though. Do you think this is different from a "MediaWiki Developer Hub"? Let's talk, and let's push this good energy in the right direction!--Qgil (talk) 23:35, 8 January 2014 (UTC)

S Page (WMF),Qgil from Developer hub… "It is written for skilled LAMP developers who have experience using MediaWiki." I think there is overlap in the target audience but it is not necessarily the same. Perhaps the name is misleading, but the target for this is users of all types (not just skilled LAMP developers) who want to use wikimedia foundation data set or APIs to do interesting things.

Jaredzimmerman (WMF) (talk) 02:39, 23 January 2014 (UTC)

Jaredzimmerman (WMF): I agree. I've been finding it difficult to figure out the MediaWiki API (as a beginner with some programming experience). Even en:API:Sandbox is very complex and it's been hard for me to figure out where documentation is. I think that lowering the bar to entry is a very good idea. Fhocutt (talk) 20:54, 2 April 2014 (UTC)

Fhocutt, great to hear (that you're interested, not that its hard now) Will you be at Zurich Hackathon or Wikimania? we'll be working on it at both places. Jaredzimmerman (WMF) (talk) 04:40, 3 April 2014 (UTC)

Jaredzimmerman (WMF): Unfortunately no, but I am hoping to be at WikiConference USA, and I'll be contributing as part of my upcoming internship (if I am chosen!).

I agree with S Page (WMF) and I don't feel his concerns have been adequately addressed here. How to contribute was specifically designed with the "re-use our content via XML dumps and our robust API" in mind; in fact, this use-case is directly addressed in the first section of how to contribute, which links to m:data dumps and m:research:data. What's the virtue of this proposed "Data & Developer Hub"? --MZMcBride (talk) 02:33, 23 July 2014 (UTC)

True, let's address the concerns in order to have a better plan. The starting point is that Wikimedia has interesting data and an interesting MediaWiki API that most application developers out there don't know about. Even professional developers joining the Wikimedia Foundation have a hard time finding the information they need to find, learning what they need to learn. There is room for improvement, and this project wants to solve this problem. It is not going to be a short ride, although we can expect some short term results.

The URL of the project hasn't been decided, and neither the role of MediaWiki in the infrastructure of the Developer Hub, nor the future of the Developer Hub that already exists here in mediawiki.org. What the Engineering Community Team has agreed is to drive this project with the help of other contributors and to release a prototype during this quarter.--Qgil (talk) 14:22, 23 July 2014 (UTC)

Qgil: thanks for the links.

As you've stated in your reply here and at <http://fab.wmflabs.org/T488>, the goal here seems to be to focus exclusively on the MediaWiki API. We already have: (a) an entire "API" namespace here on mediawiki.org (API:Main page is the landing page); (b) the auto-generated documentation at <https://www.mediawiki.org/w/api.php>; (c) the source code itself in Gerrit, on GitHub, and at git.wikimedia.org; and (d) tools such as Special:ApiSandbox.

My cursory impression regarding this "Data & Developer Hub" is that this is an attempt to solve a lack of documentation problem with yet another forum to build and maintain.

Before there's a discussion about which cute and memorable URL to use (which is mostly a detached question, we already have redirects such as <http://bookshelf.wikimedia.org>), I'd personally like to see a clear demonstration why the current four tools (enumerated above) are insufficient. I'd like to see a clear problem statement prior to discussing potential solutions. One possible solution might be creating a micro-site (in a Git repository, I guess?), but this option is almost certainly not the best option given that you'd be slowly and painfully re-creating the giant content management system that is MediaWiki. And we already have a robust content management system installed on mediawiki.org, wikitech.wikimedia.org, and meta.wikimedia.org, among other places. --MZMcBride (talk) 05:40, 29 July 2014 (UTC)

MZMcBride, I agree, MediaWiki and mediawiki.org should provide the foundation of this project, unless there is a better short & long term plan in place. But I also believe that we can do better than sending third party developers to the current api.php, Gerrit, and even API:Main page. Compared to the Developers/API portals of other World-class web services, our offer is hard to find and navigate, and generally uninspiring. We can improve this. At http://fab.wmflabs.org/T491#11 I have tried to identify what are we missing to put MediaWiki at the center of this project.--Qgil (talk) 15:30, 29 July 2014 (UTC)

terms

Unlike most of the linked reference sites, we don't enforce developer behaviors through a Terms of Use. To replace that, it probably will help to have a terms page somewhere mentioning licensing, rate-limiting, etc. Doesn't have to be terribly high profile or anything, but something to think about including in the design.

Currently all we really have is a single legal page on dumps.wikimedia.org, which I'm surprisingly OK with content-wise, but is pretty hard to find. LuisV (WMF) (talk) 18:20, 2 April 2014 (UTC)

Rate-limiting seems fairly distinct from licensing. There are some guidelines at API:Etiquette and I think dumps.wikimedia.org is throttled (not sure where that's documented, exactly).

I agree with making the licensing information clear and easy to access. --MZMcBride (talk) 02:36, 23 July 2014 (UTC)

Good point. Task created.--Qgil (talk) 14:28, 23 July 2014 (UTC)

fab.wmflabs.org is gone, maybe Quim is talking about phab:T317. Matt Flaschen entered a number of bugs about correctly indicating the license in generated documentation (e.g. a wiki pages generally has a CC-BY-SA 3.0 footer but it may be presenting code samples or APIs published under GPL v2+). See e.g. phab:T93994 -- SPage (WMF) (talk) 09:18, 8 April 2015 (UTC)

Duplication

First requirement: don't duplicate. If this is meant to replace m:Research:Data, m:Research:Resources and similar on-wiki pages, then it needs to be able to actually do so. One possibility is to load the HTML from Meta as done for m:Project portals. --Nemo 07:55, 10 June 2014 (UTC)

Agreed. I'd like to better understand why the current set of pages (including how to contribute, which is linked from the footer of every Wikimedia wiki) are failing to address users' needs before creating additional landing pages and portals. --MZMcBride (talk) 02:37, 23 July 2014 (UTC)

Agreed, either we link or absorb, but we cannot duplicate resources. "How to contribute" is not a question that a third party developer has. Their questions sound more like "how can I use Wikimedia's API for my own benefit?". The possible answers are useful for Wikimedia contributors, but the former don't need to bother about Gerrit, hgow to get your extension deployed. etc. Again, we can find ways to present the common information to both audiences with clarity and without duplication.--Qgil (talk) 14:37, 23 July 2014 (UTC)

Build

The first thing I thought of when I saw the subject was releases.wikimedia.org. --Nemo 18:54, 25 August 2014 (UTC)

Moved again, see http://fab.wmflabs.org/T492#12.--Qgil (talk) 19:19, 25 August 2014 (UTC)

...which is now phab:T313. --AKlapper (WMF) (talk) 19:56, 8 November 2014 (UTC)

Link to prototype not working

The first link on the page "a prototype results in an error. Visiting the root http://fab.wmflabs.org shows that it has been taken offline. Is the prototype still accessible elsewhere? Is http://juliuszgonera.com/wddh/ a valid link to replace the defunct one in the interim?

Ckoerner: Thanks for noticing! We've migrated tickets from the now defunct fab.wmflabs.org so I have updated the links to work again. --AKlapper (WMF) (talk) 19:53, 8 November 2014 (UTC)

Would dev.wikimeida.org require moving content from its current sources?

I'm trying to get up-to-speed on this project. Is the idea that sections like API:Main_page and Developer_hub would be migrated to dev.wikimedia.org? If the references are to remain where they are at, what effort around the user experience is being considered? For example, it would be quite jarring to go from a really slick, high-level site (dev.wikimedia.org) to something like this. Which is a very functional and comprehensive page, but not the same as say going from https://developer.github.com to https://developer.github.com/v3/pulls/ . The latter interaction seems more cohesive as an example. My rough though is that documentation would stay where it's at and we'd use the API, or other magic, to present it on dev.wikimedia.org with a consistent UI. Is that a correct assumption?

I really do understand the need to tell people about the resources available, and to do so in a consistent and single-voice way, but at the end of the day a dev's needs are going to be different than that of the foundation. I would surmise (as a pseudo-dev myself) that folks will want quick access to information, clear descriptions once they find it, and an outlet for help if needed. I'm concerned that this effort isn't clearly stating the benefit for the developer. I've been reading a lot of what's been written, including this page itself, over the past few days. I can piece together an idea in my head, but I think there's a great opportunity to enhance the communication around why this is needed and what it will mean for developers. I hate to sound cliche and too 'salesman'-ish, but get out there and sell it!

Additionally, (just because I'm curious) - was there a RFC, interviews, or other information gathering done with existing or past developers who leveraged WMF data and information? Tell me more. :)

— Preceding unsigned comment added by Ckoerner (talk • contribs) 23:08, 12 November 2014 (UTC)

Hi Ckoerner, there is no clear plan yet to answer your questions. The future of the current Developer Hub hasn't been discussed. While it might make sense to convert API:Main_page in the homepage of de.wikimedia.org (or vice versa), this hasn't been decided either. What makes https://developer.github.com/v3/pulls/ better than API:Parsing_wikitext is better content (phab:T565) and a better layout (phab:T301#3654). I personally believe that we should have the all the API documentation in one place. If they are in different places based on the quality of their documentation, how can developers find what they are looking for? It is better to have an abrupt UI jump before finding the doc you are looking for, than not finding it at all. Also, there is a chance that having everything in one place helps the poor docs to get contributions. If we leave them in a ghetto, they will have more chances to staying in the ghetto forever. What we can do is to prioritize the most popular APIs, promote them heavily, and leave the rest for developers really looking for them. And no, there hasn't been any serious research done around this project. The root of all these planning problems is the same: lack of resources. This is why we are hiring a technical writer that feels comfortable driving this project/product to better stages.  :) Feel free diving into the dev.wikimedia.org project in Phabricator, leaving comments or asking questions in the related tasks.--Qgil-WMF (talk) 16:52, 14 November 2014 (UTC)

Hi there, WMF hired me :) Firstly, "dev.wikimedia.org" is a distraction, it's the address label on the package and not the contents of the box. The way I think of the "Data and developer hub" is it's reaching out to a different group of developers. It "encourages third-party developers to access Wikimedia data sets and use our APIs". To generalize, this group don't run a MediaWiki wiki, they don't code MediaWiki, they don't care about compatibility with older versions of the software. Hence we're developing a separate "hub" with special articles for them. But underneath it there's the same MediaWiki API that MediaWiki hackers use, and we shouldn't needlessly duplicate documentation just because two different groups make use of it, instead we can make improvements applicable to both. As for Developer hub maybe it should merge with How to become a MediaWiki hacker. (There are a lot of audiences for all our efforts, I'm a huge fan of the How to contribute page that tries to organize them.) -- SPage (WMF) (talk) 09:09, 8 April 2015 (UTC)