Topic on Project:Village Pump

We'll continue to write these articles in the existing API: namespace.

Tracked in Phabricator
Task T369

(Please read dev.wikimedia.org for some background on this project.) The articles for the new API:Data and developer hub are currently in the API: namespace. I would like the pages to be in a new dev: namespace. Here's why:

• They will render by default using a different skin, "Blueprint" (see it on the prototype). The easiest way to show articles with a different skin is using Extension:SkinPerNamespace.
• I want to use Flow on all the talk pages of these articles. The easiest way for this to happen is by setting $wgFlowOccupyNamespaces to this dev namespace.
• It's mildly useful to be able to search only these pages.
• The existing namespaces don't fit articles "to encourage third-party developers to use our data and APIs".

  Manual

  Different audience: "a technical manual for the MediaWiki software. It contains information for developers and system administrators on installing, managing and developing for the MediaWiki software."

  API

  Close, and it's what I'm using for articles to start, but an article like API:Recent changes stream is not about the MediaWiki API.

  Main (default) namespace

  proliferation of articles, hard to search.

Note the motivation to use a different skin and an easier discussion system (Flow) is that the Data and developer hub focuses on third-party developers who are not MediaWiki hackers or wiki editors. (Of course we hope some will align with our cause and contribute to our projects.)

None of these are definitive, but they lean towards creating a dedicated dev: namespace. I'm interested in technical alternatives for the first (e.g. use Extension:SkinPerPage instead, or use SkinPerCategory logic to set a different default skin). You can comment here or in phab:T369.

I agree, seems the best option.

If this is for documentation/discussion relating to the API, then why not stick with 'API' as the namespace? I think 'dev' is going to be a very confusing name, as the vast majority of this wiki (across all namespaces) could come under the category 'development'. Or 'developer'. Or whatever 'dev' stands for. And what would happen to the existing content in the API namespace?

Also, I am not sure what the purpose of an alternative skin is. Isn't that confusing, to have different parts of the site look completely different? If I'm browsing the site in Monobook, say, and then click a link to this new namespace, then I would assume I was on a different site. Doesn't seem very user-friendly to me.

Yes, I don't know why change the skin. That would be rather unexpected and shocking to a user from mediawiki.org that reaches one of those pages from RecentChanges or a link from another page.

The dicussion about the namespace is still open and we can evaluate the implications of using "API" instead of "Dev".

About the different skin, the starting point was to create an own site with own look&feel, following the example of most API/developer sites versus their products. The intention was to avoid Vector's outdated look & feel and mediawiki.org's fully charged sidebar wiith links that could be definitely confusing to third party developers not interested in MediaWiki itself or in contributing patches.

While I was among the very determined advocates of improving mediawiki.org instead of creating a separate site, I agree with the original problem. While using "a different skin in a same site" might confuse to some, I think the confusion and loss will be higher and more expensive if we stick to the current mediawiki.org interface.

In fact, I think this exercise might be useful to sanitize and improve mediawiki.org's UI. For us regular users it is easy to become blind to the problems it has, but this project is all about reaching out to new developers and engage them in the use of our APIs (which can lead to other type of contributions over time).

Here's how I think this should work:

• Use the existing API namespace for this.
  1. The name is clear and unambiguous, unlike 'dev'
  2. A new namespace leaves the question about what to do with existing API pages - move them (in which case the API namespace will end up empty, aside from redirects) or leave them (in which case we will end up with pairs of similar articles in different namespaces). Neither of these seem like a good outcome.
• Create an appropriate hub page (if it doesn't already exist) which is the focal point for this new sub-site.
• Use this as an opportunity to improve the content of that namespace as well as adding whatever other API-consumer-related documentation is appropriate. I am comfortable for the API documentation to be written with a focus on third-party use, rather than an MW developer focus.
• If there are pages in the API namespace that are not appropriate to be there, then they can be moved.
• I can sort of see why you want a separate skin, but I don't really agree with it, and I'm not sure how well it would work in practice. Unless you plan to ban internal links to other namespaces (including links to user pages), there will be plenty of places where users will 'break out' of the skin, which will be confusing for the third-party users, as much as it will be for the MW regulars who suddenly find their skin changing as they navigate the site. Perhaps a useful compromise would be to use the separate skin for anonymous (non-logged-in) visitors only. Would that work?

I've just been having a play with the proposed skin, and to be honest it leaves me a bit lost.

• I couldn't find any way to get to a discussion page.
• I eventually managed to find the edit/view history links, which are hidden away. Not sure I like the fact that editing/involvement is being discouraged in this way.
• A lot of the features I am used to (edit section, add to watchlist, save as PDF, etc.) I couldn't find at all - I assume they have simply been removed to make things 'cleaner'.

Having had a play with the skin, my feeling is that there is possibly a third approach, which might satisfy the two different camps (the people who basically want a static website that is easy to use and navigate, aimed at third-party consumers of the API vs. the people who want editable online documentation, and for it all to be in one place).

My revised suggestion is the same as what I wrote in my previous post, except that the whole skin business is abandoned - the pages are part of mediawiki.org, and remain in the site skin in the same manner as all other pages on the site. Then, in addition to this, a separate site is set up, using a variant of the new skin, which pulls it data from the API namespace of MediaWiki and presents it in a static format that is very friendly to third-party consumers. The new skin would be broadly like the prototype, with a couple of changes:

• There is no functionality related to editing, logging in, etc. except insomuch as is appropriate in relation to the next point
• There is a clear notice (possibly as part of the header, or possibly as part of the slide-out menu) saying this content comes from mediawiki.org - "to edit, discuss or otherwise contribute to it click here".

Obviously, there are details to be worked-out, but what do you think of this approach?

I'm not convinced (at all) about the idea of a separate site that will bring extra work and extra maintenance. Still, do you have any idea of how this would work and how much effort should be put to build it? My instinct says that I'd rather put that effort improving Blueprint skin.

Well, in theory there should be no maintenance required. It is effectively a read-only window into a section of mediawiki.org, and therefore once set-up it should just tick along.

I would imagine that it runs either directly off the live MediaWiki.org database or a live-replicated slave, or hooks in via the API (which would be quite apt). Either way, it is effectively a read-only mirror of a portion of mediawiki.org, skinned to be user-friendly to a subset of users who want a read-only documentation site. There will be links to edit or discuss the content (which can be as prominent, or not, as you feel is appropriate) but they link to the MediaWiki site with the standard skin.

I have no idea how much work this is. In theory, it should be fairly trivial (the hard work is in implementing the skin, which seems to be broadly done), but I don't know enough about WMF infrastructure to know how hard it is in practice.

The MusicBrainz project uses basically this system for their documentation. https://musicbrainz.org/doc/Main_Page is a read-only mirror of their wiki, using the normal MusicBrainz UI instead of their modified MonoBook.

This is the page explaining how they do it (although I still don't quite see how to replicate it): https://musicbrainz.org/doc/WikiDocs

I chatted with devs on #musicbrainz-devel^connect.

• musicbrainz.org is a custom web server;
• admins maintain a list of wiki page revisions to transclude to it;
• a Perl module requests the HTML of those wiki pages with ?action=render, cleans up links, and stores the HTML in their server.

Hi HappyDog, thanks for engaging with us about this.

• a separate site is set up, using a variant of the new skin, which pulls it data from the API namespace of MediaWiki and presents it in a static format that is very friendly to third-party consumers
  That sounds like http://devhub.wikimedia.org! It's read-only and limited functionality, and I Special:Import mw.org content to it. The idea of configuring a separate site in production so that a single set of content can live a second lifestyle at a different host is intriguing and might have wider applicability for special sites like Wikimania, annual reports, etc., but I have no idea what the engineering challenges are. Maybe it's been done, before my time. :)

• I don't think it's a problem for new developers to encounter different skins. They'll already switch skins when they follow a link to doc.wikimedia.org or out of the API (or dev) namespace.

• We could develop logic to not show existing mediawiki.org users the Blueprint skin. Obviously "if user's skin is not default, then no Blueprint", maybe "if user is logged in, then no Blueprint" (this sounds like SkinPerNamespace's $wgSkinPerNamespaceOverrideLoggedIn = false), maybe a hidden preference or session variable to identify new visitors, or a definitive "Never screw with my skin choice!!" preference. But it's complex logic that will never catch all circumstances (e.g. long-time user browsing MediaWiki anonymously). I don't think it's the end of the world if a long-time MediaWiki user is exposed to a new skin on a few dozen pages targeted to a different audience.

• Perhaps SkinPerNamespace is the wrong idea. I would like to see the OOUI living style guide http://living-style-guide.wmflabs.org moved to mediawiki.org (phab:T93610) for similar reasons, but then we would want two different Blueprint sidebars, so two different namespaces, ... it doesn't scale. I will investigate extension:SkinPerPage and explore an explicit <skin sidebar="ooui-lsg">Blueprint</skin> in pages.

I can see the benefits and consistency of using the API: namespace as you propose, combined with api.wikimedia.org and a central focus on web API documentation. The more precise but also narrower "API" meme leaves aside datasets, websockets, and what not, but as you say we could always highlight related technologies in the main page and wherever it is appropriate. It's not that the "Dev" meme doesn't bring its own inconveniences, so we will need to evaluate both.

About the skin, I would like to ask for a chance to try it, with a plan for a quick revert if needed. The risk of user confusion is theoretical. Users deal with changes of UI by clicking links all the time. They might be confused or satisfied depending on many factors. The deployment of this extension in mediawiki.org as an optional skin has its own benefits, and would get us more feedback from users willing to give it a try.

Blueprint skin has some virtues and some problems. The possibility of being deployed in a production server contributes to highlight the serious problems and work on them. The lack of Discussion link is a known bug that I just set as blocker of the deployment of this extension in mediawiki.org. If we (and that includes you) find more blockers, we will add them. Just find/create specific Phabricator tasks to discuss them.

I have no objection to the new skin being enabled as an optional skin on mediawiki.org, for those who want to try it out.

I think there would be a lot of objections (from me and many others) if it were made the default skin, even if only for anons and/or new users.

I don't know what other people think about it being the default skin for a single namespace, but I've already made my feelings known on this.

For me, the biggest risk of confusion is the skin changing randomly as you navigate within the site. As you say, confusion within the skin itself is something that can (hopefully) be resolved by further user-testing and development. You also need to balance the ease of use for new users against the disorientation and confusion for existing users, but in most cases this can be mitigated by the fact that users can pick their own skin.

As commented here, it might make sense to have separate discussions to simplify this complex discussion:

1. Literally Deploy Blueprint on mediawiki.org as optional and experimental skin, which is useful to find technical blockers before the deployment and more testers after the deployment.
2. Implement a namespace in mediawiki.org to host the developer hub, leaving aside the skin discussion, focusing on which namespace (renovating Api:, creating Dev:, or else).
3. IF Blueprint is heading to mediawiki.org AND the namespace plan is clear, THEN discuss the combination of skin and namespace.

• I don't like the name "dev" for the namespace. I don't have any better suggestions, but dev is super confusing.
• I think this could maybe conceivably fit in the API namespace, but a separate namespace also sounds fine to me provided there is some clear criteria what does and does not belong there.
• I'm not really all that much of a fan of the Blueprint skin. More importantly I don't like the idea of half the site looking different.
  • I don't really understand the reasoning behind wanting a different skin. "Note the motivation to use a different skin and an easier discussion system (Flow) is that the Data and developer hub focuses on third-party developers who are not MediaWiki hackers or wiki editors" is not very convincing. How does having a different skin make it any easier for these users.

API:Showing_nearby_wiki_information vs http://devhub.wmflabs.org/wiki/API:Showing_nearby_wiki_information might look basically equivalent to regular users of mediawiki.org because we are used to Vector skin and the dozens of extra links in the header and sidebar (to which we are effectively blind by now). However, for new users interested only in the Wikimedia API and landing directly in one of these pages... most of those 36 links (I counted) will contribute between noise and confusion, on top of the outdated look of Vector.

Considering that most mediawiki.org users don't land lightly in Api: namespace, and those who land there probably also land in doc.wikimedia.org (which has a completely different UI), I think that offering a good experience to these new developers is better than risking a bit of confusion to some mediawiki.org users. And I still claim that such confusion is more theoretical than practical, which is why I'm proposing to run a test with a big button to revert.

Is there research on whether/when navigational bars make it harder for users to find and see the actual content of a page? Probably http://nngroup.com/ has something.

There is no lack of web design articles about navigation bars concluding that less is more. Find and see is just the beginning. Focusing on the content and navigating to next destinations comes next. In this sense, mediawiki.org's sidebar offers no benefits and many distractions to our target audience of third-party developers.

The problem with our expanded sidebar with 29 links is not only that these links can be distracting and unrelated to the topic of the page. These links have a high potential of being confusing for these third-party developers, because they include labels that might appeal to them with different meanings i.e. "User help", "FAQ", "Technical manual", "Support desk", "Sandbox".

As proposed in my comment above, let's separate topics (the namespace, the Blueprint skin, and eventually the use of a specific skin fr the namespace decided).

Back to the initial post on "Adding a dev namespace for "Data and developer hub" articles". After all the feedback received, I think it is better to NOT create a Dev: namespace, and to improve the Api: namespace instead. This change comes together with a more focused scope and a different name for the project. We will stress the more precise "Api" aspect (web APIs) instead of the more vague "developer" aspect. These are details that can be discussed in the Phabricator project.

Once the namespace topic has been agreed, we will discuss the skin topic.

The problem there is that the "API" namespace is currently for the api.php action API. If you try to make it about APIs more generally (restbase, rcstream, etc) things might get a bit confusing on pages like API:Main page, API:Localisation, API:Calling internally, API:Client code, API:FAQ, and so on.

Yes, it is clear that we cannot just throw the new pages in Api: without considering the existing content. Still, the end result should be useful: all documentation about our web APIs in one place. Once we agree on the principle, S could plan carefully the next steps with the help of Anomie and other regular editors in that namespace.

While I welcome the focusing of scope around the better-defined "web APIs" designation, I think we must keep in mind that api.php is a mediawiki feature that all MW wikis will have access to, while other web APIs depend on WMF infrastructure and Wikimedia wikis' content. On the other hand, other MW features don't have their own namespace, so I guess it might work to transition the namespace to include other APIs. The problem remains of confusion between "the" MW API (api.php) and other APIs, but that's a transversal issue to the namespace discussion. If we make sure api.php documentation remains well organized and navigable, I suppose it could work.

I have created T105133 Organize current and new content in the API: namespace at mediawiki.org as a blocker of our quarterly goal.

I retract the proposal to add a 'dev:' namespace (for now).

The new articles are already in the 'API:' namespace, along with 150 pages in English plus translations. The 'API:' namespace is mostly about the MediaWiki PHP API, but that's not carved in stone anywhere. What makes the MW API somewhat navigable is {{API}} on most of those pages, which displays "[This page is part of the MediaWiki API documentation.]" along with "MediaWiki API" contents. These articles don't have that template, nor would other potential pages about RESTBase API, or reusing content.