Help:Extension:CollaborationKit

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: 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.
 * 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.

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.

Setting up
Setting up a new Collaboration Hub is easy:
 * 1) Make sure that you have the necessary user permissions to create pages and change content models.
 * 2) Go to Special:CreateCollaborationHub
 * 3) Fill out the form. Details include:
 * 4) * 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.
 * 5) * Hub display name (optional) – A display title, if you want the title to appear to be something else
 * 6) * 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.)
 * 7) * Introduction – text introducing your project. You can use wiki markup here.
 * 8) Submit the form, and your hub will be created! You will also be added as the first member.

Navigation
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: There are also buttons on the bottom of each Collaboration Hub for accessing the main Hub editor and feature addition interface:
 * 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.



Editing interface
The Hub editing interface includes these form fields: The "Edit as JSON" button will bring you to a code editor. For more information, see the schema description at Extension:CollaborationKit/Technical_documentation.
 * 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: . The simplest way to add a new subpage feature is to just state the name of the page, as such:   – one per line, with no additional markup.
 * Footer, for content on the bottom of the page (including navboxes and categories). Wiki markup can be used here as well.

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: 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.
 * 1) 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.
 * CollaborationKit feature creation prompt.png
 * 1) Through clicking the "Add feature" on the bottom of the Collaboration Hub, as described above.
 * 2) By going directly to Special:CreateHubFeature and filling out the form.

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.

Setting up
See the instructions above for adding a feature to a Collaboration Hub. When filling out the form, specify "list of pages."

Questions and feedback
What do you think? Love it? Hate it? Want to use it on your wiki? Want to get it deployed to a Wikimedia project?
 * You can post to James Hare's talk page: User talk:Harej
 * For general discussion: Extension talk:CollaborationKit or the WikiProject X discussion page.