Help:Extension:CollaborationKit
| File:PD-icon.svg | Note: When you edit this page, you agree to release your contribution under the CC0. See Public Domain Help Pages for more info. | File:PD-icon.svg |
CollaborationKit is a MediaWiki extension for building on-wiki workspaces, including WikiProjects and edit-a-thons. It was developed as part of a broader effort to improve the experience of creating and running WikiProjects.
Features include:
- Easy-to-use forms for creating and editing collaborative workspaces.
- One-click sign-up for projects, including a member list that automatically sorts active and inactive members.
- New functionality to build lists of articles to work on and selectively transclude them on other pages.
CollaborationKit introduces two new types of pages: Collaboration Hubs, which are workspaces representing a project and include tasks to work on, and Collaboration Lists, which are structured lists of pages to work on. These pages separate the content from its presentation, making it easier for bots to update the page and allowing us to build specialized editing interfaces not feasible with traditional wiki pages. That said, they can still be moved, deleted, etc. like regular pages.
For detailed technical documentation, see Extension:CollaborationKit/Technical documentation.
Principles
In designing CollaborationKit, there were some principles we kept in mind:
- Straightforward interfaces. It should be possible to figure out how to use our creation and editing interfaces with little effort. CollaborationKit was designed to fit in with MediaWiki's existing workflows as much as possible while improving on them with specialized interfaces intended for building collaborative interfaces. Of course, if you are so inclined, you can edit the underlying JSON code instead of using the editing interfaces.
- Compatibility with the rest of MediaWiki. CollaborationKit was designed to accommodate wiki novices and power users alike. Collaboration Hubs and Collaboration Lists can be moved, deleted, etc. just like other pages, and we tried to minimize visual and interface clashes that would make for a jarring experience.
- Judicious use of space. Projects can potentially have a great deal of information to handle, especially on Wikipedia where a WikiProject will often have several thousand articles in its purview. With many things to work on, it is important to highlight opportunities to do work without overwhelming users. This is why we optimize space usage on Collaboration Hubs and Collaboration Lists by making use of as much screen space as possible, making sure page elements are properly spaced, avoiding excessive whitespace, and constraining what appears on Collaboration Hubs.
- Focusing on opportunities to participate. The goals when visiting a Collaboration Hub: (a) figure out what a project is about and (b) figuring out what work there is to do. This is why, for instance, lists of project members are relegated to another page and why we replaced the traditional table of contents with a version that uses less space. The most important and relevant information should be front and center. We further advise those setting up Collaboration Hubs to put the most recent and important information closer to the top of the page, with supplemental information lower on the page.
Collaboration Hubs
Setting up
Setting up a new Collaboration Hub is easy:
- Make sure that you have the necessary user permissions to create pages and change content models.[<span title="<translate> The text in the vicinity of this tag needs clarification or removal of jargon</translate>"><translate> clarification needed</translate>]
- Go to Special:CreateCollaborationHub[<span title="<translate> The text in the vicinity of this tag needs clarification or removal of jargon</translate>"><translate> clarification needed</translate>]
- Fill out the form. Details include:
- Page title – the wiki page where this new project will be set up. This is divided into two parts: the namespace and the rest of the page title. By default, Collaboration Hubs can be set up in the project namespace or the user namespace.
- Hub display name (optional) – A display title, if you want the title to appear to be something else
- Hub theme – customization options for your project, including a theme colour and an identifying picture. (If JavaScript is disabled, you will see two separate form fields: one to input the name of an image, and another to choose the colour.)
- Introduction – text introducing your project. You can use wiki markup here.
- Submit the form, and your hub will be created! You will also be added as the first member.
Collaboration Hubs feature these elements:
- Introduction, introducing the project to passers-by. The introduction includes the "hub image," an icon identifying the project.
- The member box, off to the right-hand side, which links out to the full list of members and includes a one-click "join" button.
- The table of contents, automatically generated
- The features, which are page sections that are (usually) subpages. See below on how to create them.
- The footer.
Editing
Within the wiki interface there are three different buttons for editing, including:
- Edit, which leads to a specialized Collaboration Hub editor,
- Edit as JSON, which lets you edit the underlying source code,
- Add feature, which lets you create a new subpage that is then automatically transcluded on the Hub.
There are also buttons on the bottom of each Collaboration Hub for accessing the main Hub editor and feature addition interface:
File:CollaborationKit bottom buttons.png
Editing interface
The Hub editing interface includes these form fields:
- The hub theme field, which you may recognize from Special:CreateCollaborationHub,
- Hub display name, to set a custom display name,
- Introduction, to change the introductory text for your project. (Wiki markup can be used here.)
- Features, a listing of subpages to include. You can add new ones by listing them here or through Special:CreateHubFeature, described below. This field uses a syntax similar for galleries, with rows like this:
Project:WikiProject Women scientists/Discussions|image=discussion|display_title=Discussions. The simplest way to add a new subpage feature is to just state the name of the page, as such:Project:WikiProject Women scientists/Discussions– one per line, with no additional markup.- For the "image" option, you can use the name of any file (without the "File:" prefix) or a keyword for a pre-included icon, a list of which is available at Special:CollaborationKitIcons.
- Footer, for content on the bottom of the page (including navboxes and categories). Wiki markup can be used here as well.
The "Edit as JSON" button will bring you to a code editor. For more information, see the schema description at Extension:CollaborationKit/Technical_documentation#CollaborationHubContent.
Adding features to a Collaboration Hub
"Features" are sections on Collaboration Hubs, referring to different reports, documents, etc. featured on the main hub page of a project. They can be added in three different ways:
- Adding a line to the "Features" field of the Hub editor, described above. If you add a non-existent page title, you will be prompted to create the feature through Special:CreateHubFeature.
- Through clicking the "Add feature" on the bottom of the Collaboration Hub, as described above.
- By going directly to Special:CreateHubFeature and filling out the form.[<translate> clarification needed</translate>]
The special page for creating new features lets you pick the name of the feature (created as a subpage of the Hub), an icon for the Table of Contents, and the type of page: whether it is a generic wiki page (like any other wiki page), or a list of pages, making use of Collaboration List functionality (described below). Once the form is saved, you will be taken to your new feature, and it will automatically be embedded on your Collaboration Hub.
Note that feature embedding on Collaboration Hubs works slightly differently from regular page transclusion. For generic wiki pages, only the lead section will be shown, and for lists, only five items from each column will be shown. The idea is that Collaboration Hubs offer previews, with an option to view the full page upon request.
Collaboration Lists
Setting up
See the instructions above for adding a feature to a Collaboration Hub. When filling out the form, specify "list of pages."
From top to bottom:
- The project navbar is automatically generated, conveniently providing links back to the Collaboration Hub and other feature pages. (This is available on all subpages of a given Collaboration Hub.)
- The description, which introduces the list.
- Two columns. In this example, the two columns are called "Assess for quality" and "From Wikidata." These lists can be created by hand, or bots can come and edit the lists directly.
- Each column also has notes associated with them.
- Each list item has an associated picture, page title, and note. The picture is either automatically pulled from the article, specified manually, or there is a fallback icon that is shown.
- There are three in-line buttons per item: one to delete the item from the list, a drag-and-drop icon to re-order the item in the list, and an edit button to edit the details for that item.
- At the bottom of each column is an add new item to list button to append a new entry to that column.
Editing
The buttons described in the previous section can be used for editing individual items at a time. However, if you want to edit in bulk, you can use the Collaboration List editor. Just click the "edit" button as you would on any other wiki page.
The Collaboration List editor uses a syntax similar to galleries. If you copy and paste these examples you should be good to go.
A column with no name:
If you use the keyword "column," all lower case, then that will be interpreted as "do not give this column a name." There must be text in this area, and all Collaboration Lists must have at least one column.
---------~-~--------- column --------------------- Page one|A note for page one Page two|A note for page two
A column with a name and a note:
---------~-~--------- Column with a Name|notes=Something to say about this column! --------------------- Page one|A note for page one Page two|A note for page two
As you can see from the example, individual entries on the list take the form Page name|Note. Optionally, you can add an image with |image=Name of file.ext and a link to a different page (other than the given title) with |link=Other page (external links are not supported).
Transclude them anywhere!
You can transclude Collaboration Lists like any other wiki page. However, if you want only some of them, or you want to show them in randomized order, the {{#transcludelist}} ParserFunction can be used.
Some examples:
Embed a list with default settings (five items per column, random sorting):
{{#transcludelist:Project:Amazing Hub/To do}}
Embed only one random entry per column:
{{#transcludelist:Project:Amazing Hub/To do|maxItems=1}}
Embed ten items in the order they appear on the list:
{{#transcludelist:Project:Amazing Hub/To do|maxItems=10|defaultSort=natural}}
Embed three random items per column but with no images:
{{#transcludelist:Project:Amazing Hub/To do|maxItems=3|mode=no-img}}
Additional options will be coming shortly.
Questions and feedback
What do you think? Love it? Hate it? Recommendations for improvements? Want to use it on your wiki? Want to get it deployed to a Wikimedia project?
- For general discussion: Extension talk:CollaborationKit or the WikiProject X discussion page.
- Project work is tracked on Phabricator. You can report bugs or recommend changes through the Create Task form and adding the mediawiki-extensions-CollaborationKit tag.
