Team HQ project card best practices

Introduction

Team HQ is your personalized dashboard and project task update tool. It is a web interface for collaborating across multiple projects and teams. This document provides best practices for your day-to-day Team HQ project card workflow.

Team HQ cards

A Team HQ card is a work item (a task) assigned to a team member. It provides information such as the task's:

• title and description
• requirements and acceptance criteria
• status and progress updates
• priority and impact
• owner and assignee
• subtasks and dependencies

Write detailed card requirements

A card's requirements explain the nature, scope, and desired results of a task. This information is usually found in the card's description.

When creating a card or subtask, please provide:

• As many details as possible.
• Background information about why this task is necessary or helpful
• An example, screenshot, video, or a link to a similar (but completed) task, if it helps the assignee better understand the requirements.
• Clear goals, expectations, and deliverables of the task.

Providing clear requirements and examples reduce confusion and support efficient task completion.

Updating a card's status

You can update your teammates on the progress of a task using Team HQ's Add update feature. When updating teammates through Team HQ, we encourage you to:

• Select the appropriate status update type
• Avoid using @mentions
• Use the assignee field appropriately
• Use status updates or subtasks when blocked
• Avoid extending an active card's requirements
• Set reasonable priority levels
• Select the activity type

Select the appropriate status update type

Select the appropriate update type to alert your teammates to the nature of your update. The following summarizes the most commonly used Team HQ status update types:

The below status update types reflect advancement of the card through the primary workflow:

• requirements: The task assignee is to provide a detailed description of the task's purpose.
• estimate: The task assignee is to provide a quote of how long (in hours) it would take to complete the task.
• sprint: A task the assignee must complete.
• heroku-testing: A front-end component is ready for testing in the Heroku app.
• ready-for-pr: The assignee has completed the task and is ready to submit a pull request.
• acceptance: Verify that the task's results meet the pre-defined requirements.
• review: The assignee requests a subject-matter expert's feedback on the work, most commonly represented as a pull request.

The below status update types are used for general updates or to reflect that a task is blocked from progressing in the primary workflow:

• comment: A regular comment, does not change the card's workflow status. Comments are used to provide general updates or discussion related to the task.
• input: The task owner has a question requiring an answer before the task can continue.
• communication: The assignee needs internal or external communication to complete the task.

While available, the below status update types are commonly on used by the project owner:

• new: This is a new task and is assigned to the project owner for further scoping and clarification.
• backlog: All the work the assignee is yet to complete.
• archived: The task assignee has completed the task, and is archiving it for future reference.
• dropped: The task owner or assignee has dropped this task. It is no longer required.

Avoid using @mentions

Using @mentions in a task update sends a message to the assignee's Mattermost chat. This can be a distraction or a lifesaver, depending on the urgency or priority of the message in the update. To this end, we encourage you to:

• Use @mentions in an update only if it's a time sensitive or a high-priority status update.
• Use appropriate Markdown formatting to draw the assignee’s attention to important parts of the update.

Use the assignee field appropriately

A card's assignee is the person who needs to take action on the task next. Modifying a card's assignee is not required for all comments or status updates.

Only change a card's assignee field when you are transferring task ownership.

Use status updates or subtasks when blocked

As the current task assignee, if you are blocked and need assistance or information from another team member to progress, consider one of the following:

• Provide an input or communication status update and assign the task to the person best qualified to answer your query.
• Create a new card that is a subtask and assign it to the appropriate person.

The benefits of creating a new card that is a subtask as opposed to re-assinging the primary task are:

• If you have multiple blocking issues, each can be reflected and tracked independently with a separate subtask
• The primary task continues to appear on your Team HQ dashboard, while the subtasks appear on the respective assignee's dashboard

Avoid extending an active card's requirements

A task's requirements can change as it evolves. When a task's requirements change, avoid extend an active card's original requirements. Instead, we encourage you to:

• Create a new independent card
• Create a subtask under the existing card

Creating a new card or subtask instead of extending card requirements:

• helps teams stay on task
• reduces ambiguity in requirements
• promotes task-specific discussion
• gives the card owner a clear overview of the progress made

Set reasonable priority levels

Team HQ uses a priority scale of 1 to 5, where 1 is the highest priority and 5 is the lowest. Set a reasonable priority level in your update or subtask. This gives a teammate a sense of how urgent the update is.

Select the activity type

The activity field of a Team HQ card update is like the type field. It gives the reader an idea of what the update might be at a glance. To improve communication, select the appropriate activity type when writing update messages. Doing so gives the update's assignee a sense of what the update is about.

Link cards to Cyans topics

Linking a card to a Cyans has the following advantages:

• It displays each message in the related Cyans topic as an update in the card's timeline.
• Gives the card owner, assignee, and other team members context into the card's progress without them leaving Team HQ to review messages in Cyans.

When you create a card, link that card to an existing Cyans topic as follows:

1. Visit https://cyans.linkorb.com and sign in if you're not already signed in.
2. Click the topic to which you want to link the card.
3. Click Reply button.
4. Type /link card 1234 (replace 1234 with the card's number). See Linking topics to external entities for more information.
5. Click Send

If the card does not have an existing Cyans topic, create a new topic from the card's page as follows:

1. Click the + TOPIC button in the Links section of the card's page.

   

2. Write a message and select the topic's participants. If you're unsure of which participants to select, only add the card owner and the assignee.

3. Click the green Start topic button at the bottom of the page.

Make this documentation better!

Do you have any feedback on how to improve this guide? Create a Cyans topic now to discuss this with the appropriate teammate(s).