Community Tech/Tool Labs support/Notes

Hackathon, April 3

Audience and goals

Brand-new developers just learning about building wiki tools
Creator of a new tool
User looking for an existing tool
Maintainers of existing tools

Brand-new developers

Starting on the Tool Labs portal: I know a little bit about programming language X; now I want to make a thing.

What they need: a concise "Hello, World!" when they create an account, walking through the signup and installation instructions.

There's information currently on Tools, but it's full of jargon, and the instructions are solution-oriented rather than task-oriented. You already need to know what you need to know, in order to find it. Much of it was written by sysadmins as notes to themselves.

Example: information about how to run a job or a bot is labeled "Grid" in the navbar, which is impenetrable. That's an accurate name for the page, because it's about using the Grid system, but new people need a more obvious path to get there.

An example of the kind of wizard we need is Heroku, a layer on top of Amazon Web Services. Signing up is free, and they walk you through the steps, introducing everything in sequence, as you need it. Depending on the language you're using, you get slightly modified documentation that's specific to your language. This is a free tier that's pointing towards a paid service, so it's focused like a laser on getting people through the funnel.

Building a wizard on Tool Labs is a goal to work towards; it's too big to take on right away.

Creator of a new tool

Right now, Create New Tool takes you to a page asking for the service group and the name of the tool. People don't realize that "service group" is another name for the tool, that it's going to be the URL, and that it needs to fit a specific limit. That page doesn't give you a field for a description, because it involves making a description file, or a JSON file. This impacts the browsing user, below.

There's a question about what license to use, but no prompt to learn about free and open-source.

There should be a button that says click here, and get a Git repo. You have to go to Gerrit and figure it out yourself.

User looking for an existing tool

I heard there's a tool that does X, but I can't find the link.

Needs: A way to browse the Tools directory, which is currently not set up for browsing.

Similar use case -- I have an idea for a tool, and I want to see if there's already an existing tool that solves that problem.

The Tools directory page is hard to browse, and it's missing some helpful information -- like a description of the tool -- because the Create New Tool process doesn't help you do that. (See above.)

(Idea from Benoît: Being able to sort by the most-used tools, using whatever definition is most relevant.)

People mainly discover tools through word of mouth -- on-wiki, on IRC.

Tool owners and maintainers

Grid Status page has a huge table of all the tools.

Owners can add people as maintainers, through the Tools directory. That gives other people an invite and access to Tool Labs.

Maintainers need instructions on what to do when your tool breaks -- how to restart the service, what logs to look at.

Why would encouraging active collaboration on Tool Labs help?

Find people who could be maintainers
Folks looking for a tool to help with
A way for people to report a bug
The Tools directory needs categories/tags to help with browsing
Giving people thanks/thumbs-up for their help; it makes people feel good, and encourages them to come back.

The game-changing interaction is the first time you get a pull request -- somebody found my code, and read it, and cares enough about it to make a change! That's the link between people that could make Tool Labs powerful.

Collaboration is going to make a better end product; we know that, we're wiki people.

Uploading your unfinished source code helps you get past the "writer's block" problem -- I don't want to publish this because it's not perfect yet.

Also: the documentation on Wikitech sucks! A community that cares about it as a wiki could help fix and maintain the help pages.

Needs public communication channels for bot and tool developers. A tool maintainer Village pump -- "The Forge"

Seed with blog posts on the theme of "This is how I did X" -- basically, let me show you how clever I am. These could help make Tools a "destination".

Tools isn't an SUL wiki. If you use OAuth, it should generate a user page for you.

A key goal: Helping weekend developers level up, and turn their project into an open-source tool that's maintained by a group of people.

June 23, goals

Goals from Q4 that are done:

Made the vision page, had community discussions about the scope of the project, got buy-in on the plan
Published Tool Labs survey results, which were announced on Labs-l and Wikitech-l, with some discussion
Worked with TCB to get Merlissimo to accept other people maintaining MerlBot.
(Started work on Striker, delivered early next quarter.)

Q1 goals:

1 + 2: Launch Striker, a tool that connects developers' LDAP account with their Wikimedia user account, and allows them to easily create and manage an associated git repository -- underway, will be finished early Q1. (This will encourage people to publish their source code.)

3: Build an extension for Horizon that can manage the Puppet config -- being done by the Labs team.

4: Evaluate replacement for Sun Grid Engine -- done, we're using Kubernetes.

5: Extend Striker to help new developers create an LDAP account and manage their SSH keys, removing barriers in the new account creation process -- a goal for Q1. (This makes the new person onboarding a lot easier, fixes the confusing process, removes barriers for new volunteers.)

7: Set up process/criteria for taking over abandoned tools -- community discussion, a goal for Q1. (See: Merlbot incident for an example of what happens when there isn't a working process.)

Aug 18, midpoint check-in

Striker is on track to deploy next week, Aug 24th, hooray. It will:

connect your LDAP account, you can authorize it with your wikitech name and password
if you're logged in, prompt you to connect your SUL account for undescribed benefit
then searches Phabricator for your LDAP and SUL names, and connects to your Phab account, or creates one
then checks if you're a member of the Tools project -- if not, prompts you to do that
then checks if you're a maintainer of any tool -- if not, it prompts you to create your Tool account
then looks at all the things you're maintaining, and if none of them has a Git repo, it makes one and sets it up so that you and other maintainers have rights in Phabricator.

Hasn't worked on the "Extend Striker" part yet -- he can work on it once Striker is deployed.

Next up: Start the community discussion about process for taking over abandoned tools. Probably start the conversation at Labs-L and then start an RFC on Meta. He's going to put together a straw man proposal; I should bug him about it in the first week of September.

Also, going to do a presentation, probably at Oct's Wiki conference, and then at Wikimania: Bot Licensing. Talking to on-wiki bot approvers to establish a process of review before they become dependent on a bot. Bot approvers should:

ask to see the source code with license
encourage bot writers to have a co-maintainer
encourage on-wiki documentation that says what the bot does, how to run it, how to shut it down if it's gone rogue.