A proposal for better tool discoverability

classic Classic list List threaded Threaded
8 messages Options
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

A proposal for better tool discoverability

Hay (Husky)
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

_______________________________________________
Toolserver-l mailing list ([hidden email])
https://lists.wikimedia.org/mailman/listinfo/toolserver-l
Posting guidelines for this list: https://wiki.toolserver.org/view/Mailing_list_etiquette
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

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

Magnus Manske-2
Thanks Husky,

I've added WDQ to try it. At what interval does it refresh?

It might be helpful if I could structure (group) tools on the wiki page. Does the directory ignore not-well-formatted lines (e.g. headings)?

Cheers,
Magnus



On Wed, Aug 13, 2014 at 4:15 PM, Hay (Husky) <[hidden email]> wrote:
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

_______________________________________________
Labs-l mailing list
[hidden email]
https://lists.wikimedia.org/mailman/listinfo/labs-l


_______________________________________________
Toolserver-l mailing list ([hidden email])
https://lists.wikimedia.org/mailman/listinfo/toolserver-l
Posting guidelines for this list: https://wiki.toolserver.org/view/Mailing_list_etiquette
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

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

Magnus Manske-2
Also: Can the directory detect arrays? For example, in the "wikidata-todo" tool, I have many smaller tools. I could make a file for each, but that seems overkill.

Directory tool could do "object=>single tool", "array=>multiple tools in one file".

Cheers,
Magnus


On Wed, Aug 13, 2014 at 4:53 PM, Magnus Manske <[hidden email]> wrote:
Thanks Husky,

I've added WDQ to try it. At what interval does it refresh?

It might be helpful if I could structure (group) tools on the wiki page. Does the directory ignore not-well-formatted lines (e.g. headings)?

Cheers,
Magnus



On Wed, Aug 13, 2014 at 4:15 PM, Hay (Husky) <[hidden email]> wrote:
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

_______________________________________________
Labs-l mailing list
[hidden email]
https://lists.wikimedia.org/mailman/listinfo/labs-l



_______________________________________________
Toolserver-l mailing list ([hidden email])
https://lists.wikimedia.org/mailman/listinfo/toolserver-l
Posting guidelines for this list: https://wiki.toolserver.org/view/Mailing_list_etiquette
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

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

Hay (Husky)
Hey Magnus,
thanks! WDQ is now added to the directory. The cronjob should run every hour.

Having a list of tools as an array is something i've been thinking
about as well, will probably add that.

'Grouping' tools can be done by simply adding a category. Or do you
mean something else?

-- Hay

On Wed, Aug 13, 2014 at 5:56 PM, Magnus Manske
<[hidden email]> wrote:

> Also: Can the directory detect arrays? For example, in the "wikidata-todo"
> tool, I have many smaller tools. I could make a file for each, but that
> seems overkill.
>
> Directory tool could do "object=>single tool", "array=>multiple tools in one
> file".
>
> Cheers,
> Magnus
>
>
> On Wed, Aug 13, 2014 at 4:53 PM, Magnus Manske <[hidden email]>
> wrote:
>>
>> Thanks Husky,
>>
>> I've added WDQ to try it. At what interval does it refresh?
>>
>> It might be helpful if I could structure (group) tools on the wiki page.
>> Does the directory ignore not-well-formatted lines (e.g. headings)?
>>
>> Cheers,
>> Magnus
>>
>>
>>
>> On Wed, Aug 13, 2014 at 4:15 PM, Hay (Husky) <[hidden email]> wrote:
>>>
>>> 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
>>>
>>> _______________________________________________
>>> Labs-l mailing list
>>> [hidden email]
>>> https://lists.wikimedia.org/mailman/listinfo/labs-l
>>
>>
>
>
> _______________________________________________
> Toolserver-l mailing list ([hidden email])
> https://lists.wikimedia.org/mailman/listinfo/toolserver-l
> Posting guidelines for this list:
> https://wiki.toolserver.org/view/Mailing_list_etiquette

_______________________________________________
Toolserver-l mailing list ([hidden email])
https://lists.wikimedia.org/mailman/listinfo/toolserver-l
Posting guidelines for this list: https://wiki.toolserver.org/view/Mailing_list_etiquette
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

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

Pleclown
My tools are all under a unique directory, https://tools.wmflabs.org/ptools/ with a different php file for each. How should I construct my .json file ?

Pleclown


On Wed, Aug 13, 2014 at 6:16 PM, Hay (Husky) <[hidden email]> wrote:
Hey Magnus,
thanks! WDQ is now added to the directory. The cronjob should run every hour.

Having a list of tools as an array is something i've been thinking
about as well, will probably add that.

'Grouping' tools can be done by simply adding a category. Or do you
mean something else?

-- Hay

On Wed, Aug 13, 2014 at 5:56 PM, Magnus Manske
<[hidden email]> wrote:
> Also: Can the directory detect arrays? For example, in the "wikidata-todo"
> tool, I have many smaller tools. I could make a file for each, but that
> seems overkill.
>
> Directory tool could do "object=>single tool", "array=>multiple tools in one
> file".
>
> Cheers,
> Magnus
>
>
> On Wed, Aug 13, 2014 at 4:53 PM, Magnus Manske <[hidden email]>
> wrote:
>>
>> Thanks Husky,
>>
>> I've added WDQ to try it. At what interval does it refresh?
>>
>> It might be helpful if I could structure (group) tools on the wiki page.
>> Does the directory ignore not-well-formatted lines (e.g. headings)?
>>
>> Cheers,
>> Magnus
>>
>>
>>
>> On Wed, Aug 13, 2014 at 4:15 PM, Hay (Husky) <[hidden email]> wrote:
>>>
>>> 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
>>>
>>> _______________________________________________
>>> Labs-l mailing list
>>> [hidden email]
>>> https://lists.wikimedia.org/mailman/listinfo/labs-l
>>
>>
>
>
> _______________________________________________
> Toolserver-l mailing list ([hidden email])
> https://lists.wikimedia.org/mailman/listinfo/toolserver-l
> Posting guidelines for this list:
> https://wiki.toolserver.org/view/Mailing_list_etiquette

_______________________________________________
Toolserver-l mailing list ([hidden email])
https://lists.wikimedia.org/mailman/listinfo/toolserver-l
Posting guidelines for this list: https://wiki.toolserver.org/view/Mailing_list_etiquette


_______________________________________________
Toolserver-l mailing list ([hidden email])
https://lists.wikimedia.org/mailman/listinfo/toolserver-l
Posting guidelines for this list: https://wiki.toolserver.org/view/Mailing_list_etiquette
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

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

Danmichaelo
In reply to this post by Hay (Husky)
It's great if this catches on, but we need a way to express multiple authors. Could we have an "authors" field instead of "author", and use an array instead of a string? I would also prefer "keywords" to be an array instead of a comma-separated string.

It would also be great if the description could be fetched from the ~/.description file read at http://tools.wmflabs.org/ if not specified in the .json file. I would prefer to maintain a description of my tools in one place rather than in two. Perhaps maintainers could also be fetched automatically if not specified manually?

Dan Michael


On 13 August 2014 17:15, Hay (Husky) <[hidden email]> wrote:
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

_______________________________________________
Labs-l mailing list
[hidden email]
https://lists.wikimedia.org/mailman/listinfo/labs-l


_______________________________________________
Toolserver-l mailing list ([hidden email])
https://lists.wikimedia.org/mailman/listinfo/toolserver-l
Posting guidelines for this list: https://wiki.toolserver.org/view/Mailing_list_etiquette
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

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

Magnus Manske-2
In reply to this post by Hay (Husky)



On Wed, Aug 13, 2014 at 5:16 PM, Hay (Husky) <[hidden email]> wrote:
Hey Magnus,
thanks! WDQ is now added to the directory. The cronjob should run every hour.

Having a list of tools as an array is something i've been thinking
about as well, will probably add that.

Thanks, I'll hold off some of my tools then, until this is done.

'Grouping' tools can be done by simply adding a category. Or do you
mean something else?

I mean, visually separating groups on your wiki page, within the <source> tag. Easier to check if I have a tool added there if mine are all in a "section". But not really a show-stopper :-)

This is great!

Cheers,
Magnus

_______________________________________________
Toolserver-l mailing list ([hidden email])
https://lists.wikimedia.org/mailman/listinfo/toolserver-l
Posting guidelines for this list: https://wiki.toolserver.org/view/Mailing_list_etiquette
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

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

Hay (Husky)
Hey everyone,
thanks for all the positive feedback! I've only released the tool 8
hours ago, and we already have 30 tools listed. Awesome! Let's try to
get it to 100 in the next few days :)

I've released a new version (http://tools.wmflabs.org/hay/directory)
that incorporates a few of the suggestions here:

* It's now possible to add multiple tools to one toolinfo.json file.
Simply stick your tools in an array instead of an object. Here's an
example:

http://tools.wmflabs.org/hay/toolinfo.json

* Because of this new format it's important to have a unique `name`
property. This should preferably be something like
'yourusername-toolname'. For the 'pretty' title in the directory use
the new 'title' property. The current name will now be used as a
title, but this will probably be deprecated in the future, so change
your toolinfo.json files accordingly.

* Toolnames are no longer needed on the Directory page on the Wikitech
wiki. Just an URL is enough. I've updated this page to reflect the new
format. Comments (preceded by a # hash) are now allowed to structure
the file better.

* You can now add multiple authors to a tool. Simply separate by
comma, just like the keywords. I considered using arrays for
keywords/authors, but it was a bit of a hassle on the database, so for
now i'm sticking with commas (hopefully nobody has a name with a comma
in it :)

* I've added a very rudimentary ranking system, using the number of
clicks on the tool as a metric (no IP's or anything are recorded, just
number of clicks).

Keep on submitting those toolinfo.json's!

-- Hay / Husky

On Wed, Aug 13, 2014 at 9:38 PM, Magnus Manske
<[hidden email]> wrote:

>
>
>
> On Wed, Aug 13, 2014 at 5:16 PM, Hay (Husky) <[hidden email]> wrote:
>>
>> Hey Magnus,
>> thanks! WDQ is now added to the directory. The cronjob should run every
>> hour.
>>
>> Having a list of tools as an array is something i've been thinking
>> about as well, will probably add that.
>
>
> Thanks, I'll hold off some of my tools then, until this is done.
>>
>>
>> 'Grouping' tools can be done by simply adding a category. Or do you
>> mean something else?
>
>
> I mean, visually separating groups on your wiki page, within the <source>
> tag. Easier to check if I have a tool added there if mine are all in a
> "section". But not really a show-stopper :-)
>
> This is great!
>
> Cheers,
> Magnus
>
> _______________________________________________
> Toolserver-l mailing list ([hidden email])
> https://lists.wikimedia.org/mailman/listinfo/toolserver-l
> Posting guidelines for this list:
> https://wiki.toolserver.org/view/Mailing_list_etiquette

_______________________________________________
Toolserver-l mailing list ([hidden email])
https://lists.wikimedia.org/mailman/listinfo/toolserver-l
Posting guidelines for this list: https://wiki.toolserver.org/view/Mailing_list_etiquette
Loading...