[Labs-l] A proposal for better tool discoverability

[Hay (Husky)]

Hey everyone,
thanks for all the compliments again! At the moment of writing, and
just two days after the launch we've already got 125 tools in the
directory. Awesome!

Some comments on some of the questions posted here:

Magog wrote:
> Question: will the tool choke and/or emit unwanted error messages if it finds JSON fields it doesn't recognize?
> Because these are a sneaky way to include comments (http://stackoverflow.com/q/244858).
Yes, this is indeed possible. The tool only checks for the required
properties, and simply ignores anything it can't insert in the
database, so feel free to add any comments using this method.

Another thing to note: the 'toolinfo.json' filename is just a
convention. If you would create a php script that generates the valid
format and you add the URL pointing to that to the wiki page the tool
will work as well.

Harry wrote:
> Neat! I still think that the only way you'll get good adoption is to have an online form,
> forced on you when you create a tool... that particular horse may have already bolted, of course.
Well, this is still possible, right? :) Or we could at least write in
the help section on the toolserver as a best practice.

TParis wrote:
> Might also be useful to know if a tool has an API and if the source code is viewable.
Svetlana wrote:
> Maybe also indicate a tool source code license? Would be adorable
I'm a bit wary about adding too many properties. Given that we've
already got a 'repository' property we can assume that every tool with
that property is also open source. Indicating that an API is available
can be as simple as adding an 'api available' keyword.

Marc-André wrote:
> I would actually prefer that the json file live in the tool's home, and
> will shortly provide a means by which this can be fetched by HTTP.  Not
> all tools provide web interfaces, and metadata about those would be just
> as useful.
I'm not quite sure what you mean by this. This is the case for all
tools currently, right?

> It would also make sense to have more than one url element; one
> (optional) for a web interface, for instance, and one to documentation
> at the least.
I think this would complicate matters too much. If you have a non-web
tool, simply write a documentation page, or put something up on a wiki
somewhere and put that url in the 'url' field. The WikiLinkBot is a
good example of this practice.

(about replacing the current homepage of tools.wmflabs.org)
> I don't know about /replacing/ it, but if we used that new metadata to
> improve it that would be +good.
I agree that even though the current homepage is severely broken for
discoverability it does have a few uses. Maybe we could use the
'Hosted tools' page as a separate tab or page?

On the other hand, the Tool Directory is not just for Tool Labs-hosted
tools, so maybe replacing it would falsely suggest that it's an index
of only Tool Labs-hosted tools.

Hedonil wrote:
> Wrote down some thoughts about the data structure of a unified directory service
Thanks for spending time on thinking and writing down alternatives.
I'm not quite sure about separating the code of the tool from the
actual metadata. IMHO this will cause neglect on the author's part,
because it will be very common to forget to update (or even write)
metadata like that in a completely separate system. Having the
metadata on the tool in a simple format, together with the code, will
make sure tool authors will at least put a little bit of effort in
keeping it up-to-date.

One thing i'd like to mention in general: note that it's not at all
required to host your tool on the toollabs instance to have it in the
directory. If you have a tool living on your own server, a Javascript
gadget living on a Mediawiki project, or even hard-to-find tools that
are part of a standard Mediawiki installation feel free to add that as
well to the tool directory. In the future we might have some kind of
standard categorization, but for now i would like to first see how the
directory evolves before we start introducing more properties.

Kind regards,
-- Hay / Husky




On Fri, Aug 15, 2014 at 12:20 PM, Harry Burt <jarry1250 at gmail.com> wrote:
> Neat! I still think that the only way you'll get good adoption is to have an
> online form, forced on you when you create a tool... that particular horse
> may have already bolted, of course.
>
> Harry
>
>
> On Fri, Aug 15, 2014 at 10:58 AM, Magog The Ogre <magog.the.ogre at gmail.com>
> wrote:
>>
>>
>> Question: will the tool choke and/or emit unwanted error messages if it
>> finds JSON fields it doesn't recognize? Because these are a sneaky way to
>> include comments (http://stackoverflow.com/q/244858).
>>
>> Also, Hay, you are a coding, documentation, and implementation genius. :-)
>>
>>
>> On Friday, August 15, 2014, TParis <tparis.wiki at gmail.com> wrote:
>>>
>>> Might also be useful to know if a tool has an API and if the source code
>>> is viewable.
>>>
>>> -----Original Message-----
>>> From: labs-l-bounces at lists.wikimedia.org
>>> [mailto:labs-l-bounces at lists.wikimedia.org] On Behalf Of svetlana
>>> Sent: Thursday, August 14, 2014 6:52 PM
>>> To: labs-l at lists.wikimedia.org
>>> Subject: Re: [Labs-l] A proposal for better tool discoverability
>>>
>>> On Thu, 14 Aug 2014, at 22:59, Hay (Husky) wrote:
>>> > Hey Hedonil,
>>> > thanks for the suggestion for a 'repository' property, i've added
>>> > that. Adding it now adds a 'source available' link in the tool card,
>>> > and also groups them in a special category.
>>> >
>>> > -- Hay
>>>
>>> Maybe also indicate a tool source code license? Would be adorable
>>>
>>> svetlana
>>>
>>> _______________________________________________
>>> Labs-l mailing list
>>> Labs-l at lists.wikimedia.org
>>> https://lists.wikimedia.org/mailman/listinfo/labs-l
>>>
>>>
>>> _______________________________________________
>>> Labs-l mailing list
>>> Labs-l at lists.wikimedia.org
>>> https://lists.wikimedia.org/mailman/listinfo/labs-l
>>
>>
>> _______________________________________________
>> Labs-l mailing list
>> Labs-l at lists.wikimedia.org
>> https://lists.wikimedia.org/mailman/listinfo/labs-l
>>
>
>
> _______________________________________________
> Labs-l mailing list
> Labs-l at lists.wikimedia.org
> https://lists.wikimedia.org/mailman/listinfo/labs-l
>