Working on documentation for the Mozilla Developer Network often involves larger documentation projects. To plan, schedule, and track the status of these projects, we've started using Trello. This article describes how we use Trello for this purpose.
Trello is an easy-to-use Web-based task tracking system. To learn more about Trello itself, see the Trello Help pages.
Our use of Trello relies on the notion of a documentation project. A documentation project is a set of documentation, rather than a single correction or update. Some examples of what might be considered a documentation project are:
- Documentation for a completely new API
- A collection of enhancements to an existing API due to a substantial specification change
- Implementing an all-new technology
- Adding a new tutorial series on a particular topic
- Adding live samples to a set of documentation (such as the HTML Reference).
A documentation project would not be something like "correct a typo on page X" or "document one new method on interface Y."
The main concept to understand about Trello is that each project is represented by a card. Each card has two sides. The front of the card looks like this:
Here we see the "MDN User Guide" project's card. This card has been upvoted once by a user interested in seeing the project completed. It has 18 checklists attached, two of which have been completed. And the project has been assigned to the user whose photo is shown (that's Eric Shepherd, MDN's documentation lead).
You can see more details about the project by clicking on the card to "flip" it to see the back. Here's what the back looks like:
At the top of the back of the card is the card's name, which column it's in, and other information, including:
- The number of votes. Clicking this presents a list of all the Trello users that voted for the project.
- The number of checklists the card has and the number of them that have been completed.
- The card's description. This is a text field you can use to provide additional information about what's involved in the project, links to relevant bugs and content, etc. In this case, there's no description, just a link you can click to create one.
- Below that is the task list, which we'll look at separately.
In the right column of the card's back are an assortment of controls and options:
- You can add one or more labels to each card. There are six different labels available, three of which we currently use. See Using labels below.
- A list of users that are assigned to the project, indicated using their avatar images. Clicking the Assign button lets you search for other users to assign to the card (including yourself, of course).
- Add checklist
- A card can have multiple checklists. In the card shown above, you see several, such as "About MDN," which currently has two tasks on the list. You can create a checklist for each document you need to create for the project, for example, as done here, or use them in other ways as appropriate for your project. See Using checklists below for more information.
- Due date
- If the documentation project needs to be completed by a specific date, you can set that date (and optionally the time) here. For example, if a documentation project needs to be completed before the launch of a given version of Firefox, you could set its beta (or Aurora, or whatever) date as the due date for the card, as appropriate.
- Attach file
- You can attach files to cards. For example, there might be notes from meetings, screenshots, code samples, etc. You can attach files from your computer, Google Drive, or Dropbox. Keep in mind that everyone will have access to these files.
- This option lets you move the card. You can move it to another column (although that can be done by dragging it, too), or to a different board entirely (although this should never be necessary). You can also change its position in the column, although that can also be done by dragging it around the board.
- You can subscribe to cards; when subscribed, you'll receive notifications when changes are made to the card. This is a great way to monitor the progress of a documentation project that interests you, or to keep abreast of changes made by people you're collaborating with.
- The Vote button lets you vote (and revoke your vote) on the card. Voting on cards is a way to indicate how important you think a documentation project is. The more votes a project gets, the more interest there is in it, and the more likely it is (in theory, anyway) that someone will pick it up to work on.
- Once a card is no longer needed (typically once it's been completed and covered in the MDN community meeting), it can be archived. That takes it off the board, but keeps it and its data around in case it's needed later.
The More button offers a few additional options:
- Lets you copy the card. This should rarely if ever be useful, but the option is there.
- Lets you print the card (although to be honest, I can't see that this actually does anything, at least in Firefox).
- Export JSON
- Exports the card's data in JSON format.
- Card #
- The card's ID number.
- Link to this card
- A text field (not editable) providing a permanent link you can use to link directly to the card. This is useful for sharing the status of your documentation project with others.
- The date and time at which the card was initially created
- This link lets you delete the card. Please don't use this unless the card was literally created in error. Instead, archive the card.
- Ready to move to next column (Green)
- When a card is ready to be moved to the next column, add this label. Sometimes a card will be ready to move on, but nobody is available to handle that next step, so you can simply add this label, so that the writing community knows that the stage it's currently in has been completed and that they can take it to the next level if time is available. Once the card is moved, be sure to remove this label!
- Gathering information (Yellow)
- Information is being collected. Apply this label when you're reviewing requirements, reading over code samples, etc, but not actively writing content.
- Waiting for response to questions (Orange)
- This should be applied to a card when questions have been sent to the development team, and a response is being awaited.
Trello provides colored labels that you can use to categorize cards. There can be up to six of them; currently we use three:
The "Ready to move to next column" label is the one that will likely see the most use.
Each card may have any number of checklists on its back. Each checklist has a name plus one or more items that need to be completed. A thermometer-style progress bar is shown to indicate how close to complete the checklist is. As you complete items on the list, you can click them to mark them off.
While you may use checklists as you see fit, a recommended usage is to have one for each document that's needed to complete the documentation project, then put on each list the various items that need to be covered in order to complete that document.
Alternatively, you might have just one checklist with a list of the individual documents, if further granularity isn't useful.
The current work board
The most important area of our Trello configuration is the board labeled "*Current Work*". Each column of cards here represents a stage of the documentation process:
- The cards in the Backlog column represent projects that are ready to be written about but do not yet have a writer working actively on them. When a writer starts work (either by being assigned to a given project, or choosing to do it), the card is moved to the next column.
- Information Gathering
- The cards in the Information Gathering column represent projects that a writer has begun preparing to write up. Generally, this is where initial information gathering occurs, to determine what needs to be done, collect reference material and code samples, and so forth. Once the writer has enough information to write about the topic, the card is moved to the next column.
- Cards in this column represent projects being actively written about; one or more people are working on producing the content, including prose and live code samples. When writing is complete, the card moves to the next column.
- Once writing is complete, it's time for the content to undergo reviews. This includles both technical and editorial reviews. It's worth noting that in reality, this may be going on alongside the writing work, especially for larger, multi-page writing projects. This phase also includes implementing suggested corrections and revisions to the content. Once the reviews are complete, the card moves on to the final column.
- Cards that arrive in this column represent completed documentation projects. Once the completion of the work has been covered in the next MDN community meeting, the card is removed from the board entirely.
At any time, it's possible for a card to move backward, as well, if it's discovered that a project wasn't really ready to move ahead. For example, if, during the "Information Gathering" phase, it's determined that the technology to be documented isn't really stable enough to document, it would be moved back into the Backlog. Similarly, if a card is in the "Writing" column, but work stops (due to other priorities, for example), the card should move back into the "Backlog" column.
The upcoming board
When we have projects that we don't expect to work on soon, but still need to be tracked, we add them to the separate "upcoming" board. Unlike the Current work board, the upcoming board's columns are divided up by topic area. This makes it easier for developers to find the documentation projects that relate to their area of interest more easily, and helps writers find the projects to which they've been assigned (or which they've volunteered to tackle) more easily.