New subject: [Labs-l] A proposal for better tool discoverability

13 Aug 2014

Hey everyone,
for those who attended Wikimania, i hope you all had a wonderful time!

One of the things that i've talked about at Mania with a few people is
the current way of 'tool discovery', or rather, the lack thereof.
We've seen really cool things done by the community, but i have a
feeling many of the tools go by unnoticed, simply because nobody knows
that they exist. Maybe they've been send around here or posted on IRC,
but after the initial interest many of them are forgotten and lead a
lonely life on our virtual servers.

I think this is especially problematic for non-community members for
whom the tools might be very useful. For example, as a Wikipedian in
Residence and GLAM advocate i have sent numerous mails with links to
the various GLAM tools made by Magnus, stats.grok.se, etcetera.

But, you might say, we run all these knowledge sites called wikis
right? And there are some pages there that list tools, don't they?
You're right, the community has put some efforts in a few pages (1).
However, IMHO, a wiki doesn't lend itself to easy tool discovery:

* The format on how to describe a tool is unclear, thereby leading to
both very long and very short descriptions.
* It's not possible to easily search for tools in a certain category
(e.g. 'GLAM' or 'editcount').
* The categorization of tools leads to much clicking around,
distracting and confusing users.
* There's no way to sort results, for example by the number of people
using the tool.

The biggest problem of all is the disconnection between the actual
code of the tool itself (hosted in a Git repo), and the description
advertising it. People update their tool to do something different (or
deprecate it), but they forget the documentation on the wiki, don't
remove it when the tool doesn't work anymore, etcetera.

I believe we can, and should do better.

THE PROPOSAL

My proposal is to use the same mechanisms that already exist for
package managers such as NPM (2) or 'app stores', such as the Chrome
store (3). Basically this involes adding a small JSON file to your
project, including a few key properties such as 'title' and
'description'. These files get indexed, and an easy to use frontend to
search to all the tools is provided to end users. You could imagine a
'toolinfo.json' file to look something like this:

    {
        "name" : "WikiDataQuery",
        "description" : "An API for Wikidata items and properties.",
        "url" : "http://wdq.wmflabs.org/",
        "keywords" : "wikidata, api, query",
        "author" : "Magnus Manske"
    }

If you have a web-hosted tool, simply stick it in the root of your
tools directory so that it's reachable by the crawler. Whenever your
tool data changes, just update the file and the directory will
automatically update the directory site.

The link to your toolinfo.json could be added to a Wiki page so that
it's easy to remove your tool from the directory or change the URL to
the JSON file.

I'm a firm believer in putting code where your mouth is, so i've
hacked up a working tool directory here:

http://tools.wmflabs.org/hay/directory

Try searching for stuff, clicking on the labels. To add your own tool,
scroll the page down for instructions.

Current this only lists my tools, but i hope that this directory will
soon grow with everything the Wikimedia community has to offer.

I'm interested in your opinion in this proposal and, if you like it,
add a toolinfo.json to your project!

Kind regards,
-- Hay / [[User:Husky]]

1: https://en.wikipedia.org/wiki/Wikipedia:Tools
2: https://www.npmjs.org/
3: https://developer.chrome.com/apps/manifest