Page MenuHomePhabricator

Write and post Help doc(s) for the Worklist Tool
Closed, ResolvedPublic

Description

I tried to use the Worklist tool to create a worklist but don't understand how to get started or what to do. This tool will be more useful for more people if you write clear documentation about how to use it and post the Help doc prominently on the main tool pages. Assume your users do not know anything about Petscan, etc.

Event Timeline

FYI @Surlycyborg, I was interested in trying the tool because I read a user conversation here that sounded like it was asking for just such a tool. These users' comments might be helpful/interesting to you. If you think this tool will help them, you might wish to ping them in the discussion.

GSoC is over, hence removing tag. I assume this is about The-Wikipedia-Library.
Does @Surlycyborg plan to work on this, as they were set as assignee?

GSoC is over, hence removing tag. I assume this is about The-Wikipedia-Library.
Does @Surlycyborg plan to work on this, as they were set as assignee?

The help doc requested is for the Worklist Tool (that's why this is a subtask of T187305 ).

I don't know where tasks for "the Worklist tool" are tracked I'm afraid, so I hope The-Wikipedia-Library is close. Feel free to correct.

@Aklapper, right, I believe @Meghasharma213, the GSoC student I mentored in writing the tool, is interested in staying around as a volunteer to develop and maintain the tool. I think I'll also be able to do some work on it sporadically, but Megha will likely remain the main developer going forward.

Ideally we'd prefer to track work on the tool on GitHub (https://github.com/MeghaSharma21/WorklistTool-GSoC-2018/issues/), but we could figure something out with Phabricator tickets too.

@jmatazzoni Nice, thanks for the link! I'll reply on that thread too, as both this tool and Citation Hunt (which I maintain) got mentioned.

We're definitely thinking of ways to make the tool easier to use, especially for first-time users. We're tracking progress here: https://github.com/MeghaSharma21/WorklistTool-GSoC-2018/issues/17.

I'm thinking that once we settle on the UI and actual name for the tool ("worklist" is a little boring!), we could create a page on Meta with usage instructions, and yes, link to that from the tool itself.

Until then, let's see if you can at least try it. The user experience right now is definitely rough and some things look broken now that I've tried them, but basically to create a worklist you would:

  1. Go to https://tools.wmflabs.org/worklist-tool
  2. Click Login on the top right corner, log in.
  3. Click "Create Worklist" on the top left corner.
  4. Fill in the form. This should be more-or-less self-explanatory, but you can create a worklist from a PetScan ID, though we're still struggling to make large queries work, or add individual articles by hand.
  5. Your worklist will have a URL of the form https://tools.wmflabs.org/worklist-tool/show-tasks/<YOUR USER>/<WORKLIST NAME>/, e.g., https://tools.wmflabs.org/worklist-tool/show-tasks/Megha%20(GSoC)/Petscan-test-list/
  6. You can see all worklists, or the ones you've created or are working on, by clicking "See Worklists" on the top left corner.

The worklist URL should take you to a table with one row per article, where you should be able to change the Status and Progress of articles to claim them and tell other users how far you've got in your work on them -- and these updates should be visible to other users viewing the worklist within seconds. However, this doesn't seem to be working now that I try it (I don't see the UI controls that would allow me to change Status/Progress), so I'll check with Megha.

  1. Fill in the form. This should be more-or-less self-explanatory, but you can create a worklist from a PetScan ID, though we're still struggling to make large queries work, or add individual articles by hand.

. Trust me that there is nothing self-explanatory about this. I don't know what a Petscan ID is. So...I'm stuck, a non-starter.

Also, while I'm confessing my ignorance: I don't understand what the field for "Tags" does or what I'm meant to put in there. Am I entering tags that exist already from some other system (Petscan?) or assigning brand new tags that will describe this worklist for the future? Why would I do that; what is the purpose, what type of tags are appropriate. ?

. Trust me that there is nothing self-explanatory about this. I don't know what a Petscan ID is. So...I'm stuck, a non-starter.

Oh, right, my instructions assumed familiarity with PetScan, that was not a good idea. Sorry about that.

PetScan is a tool for building complex queries on Wikipedia, based on attributes like the categories they belong to, or when they have been modified last, or how many links they contain. When you perform a query, PetScan associates an ID to it, which you can also use in a link to share with other people.

For example, I just created this query for articles about Japan containing the {{ citation needed }} template last edited this month: https://petscan.wmflabs.org/?psid=5609250 . The ID for that query is 5609250, and I could use that in the form when creating a worklist to have the tool create a worklist based on the results of the query. In fact, I did just that: https://tools.wmflabs.org/worklist-tool/show-tasks/Surlycyborg/Japan%20citation%20needed/

If you try the same, note that performing queries in PetScan can be really slow and the worklist tool will be unresponsive for a while after you submit the form, as it's performing the query server-side. This is really bad UX and we'll need to work on that, but it's best to try this with a query that results in a relatively small number of articles for now (maybe a couple of thousand, PetScan will show you the results and how many there are).

The reasoning for making PetScan the main way to define worklists is that, because PetScan is so flexible, many interesting kinds of backlog could be identified using it. For example, it might be interesting to run editathons for articles that lack links, or pictures, perhaps under a certain category or with a certain ORES score -- all of that can be turned into PetScan queries and imported into the worklist tool to produce a worklist that people can collaborate on.

Also, while I'm confessing my ignorance: I don't understand what the field for "Tags" does or what I'm meant to put in there.

I think we can ignore the tags for now (just leave blank in the form). This is an idea that Megha wanted to explore: allowing users to add any words as tags to worklists, then later search and explore worklists by tag. The searching and exploring parts are not implemented yet.

I've filled out some documentation on Github (https://github.com/MeghaSharma21/WorklistTool-GSoC-2018/pull/40), but we should add this usage to the tool itself too.

Pull Request merged, so there are now some brief usage instructions on Github. I won't mark this as resolved just yet, because we should create a Meta page too.