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.

Creating cards

A Team HQ card is a work item (a task) assigned to a team member by the task owner. 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
• sub-tasks and dependencies

Write a detailed card description

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 sub-task, provide the following:

• 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 reduces confusion and supports efficient task completion.

Selecting swimlanes and components

Swimlanes are a way to group tasks under LinkORB’s “big priorities.” Swimlanes are the “why” we are doing this work, while components are “what” the type or area of work is.

Components

Select the component that accurately describes the type of work:

Component	Description
Software development	Software development tools
Security	Security standards
Database & APIs	API specifications, database schemas, and applications
Culture and Handbook	Onboarding, communication, and project management
Technical writing	Technical documentation standards
Badges	Learning badges highlighting professional development
Blog	Blog posts
Jobs	Job postings
Astro-engineering features	New functionality added to Astro-engineering

Swimlanes

Select the swimlane that describes why the work is done:

Swimlane	Description
Attract and screen talent	Content related to job postings, pre-hire content (see “Hello Upworker!), some badge content, and blog posts targeting new/potential team members in mind
Efficiently onboard team members	Content targeting all team members regarding onboarding and using critical tooling and processes such as Team HQ, Cyans, VPNs, email, invoicing, and security
Enable technical best practices and consistency	Technical content (commit standards, PRs, coding conventions, security, badges) targeting technical team members (writers, development, test, sys administrators)
Share complex technical knowledge	Application and tool-specific content such as APIs, database schemas, herald-server, and form-server, including open-source repos and related blog content
Cultivate a healthy team and culture	Post onboarding processes and knowledge relating to badges, weekly status updates, and check-ins
Build scalable, flexible, and brand-promoting systems	All public-facing repos and sites (https://engineering.linkorb.com/, https://www.linkorb.com/) should be easy-to-administer and create a positive perception of LinkORB to candidates, customers, and members of the open-source community with quality design/UX

Selecting a parent /epic

Select a parent card if the work outlined in the present card falls under an existing parent.

If the card does not fall under an existing parent, either:

• Create a parent and assign this card to it, or
• Make this card a parent, provide a high-level overview, and move implementation details to sub-cards.

Set the status

If the card needs to be groomed or refined, set the card’s status to new. However, if the card has been refined and is ready to be assigned, update the card’s status to Backlog.

Set the priority level

Team HQ uses a priority scale of 1 to 5, where 1 is the highest priority and 5 is the lowest. Set a priority level to give the assignee a sense of the task’s urgency.

Assign the card

A card’s assignee is the person who needs to take action on the task next. Only task owners should change a card’s assignee field to transfer the task to another team member.

Link the card to a Cyans topics

Linking a card to a Cyans topic has the following advantages:

• It displays each message in the related Cyans topic as an update in the card’s Timeline.
• It 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.

Updating card status

The diagram below shows a card’s status advancement, from when the task owner creates the card to when the work is completed and the card is archived.

Statuses set by card owners

When creating a card or changing the status in the Add update panel of the card (below the card Description), the card owner sets the status to any of the following.

Status	Description
new	A card owner has been assigned to determine the scope of the card and groom the card.
backlog	The task owner has groomed the card but has not assigned the card.
sprint	The card has been assigned and is in progress if the assigned person has started work.
archived	The card assignee has completed the task, and the task owner has archived the card for future reference.
dropped	The task owner has dropped the task because it is no longer required or another card covers the work. An assigneee can only drop a task if the task owner has given permission to do so.

Statuses set by assignees

In the Add update panel, select the appropriate status to alert your teammates to the nature of your update.

The card assignee typically sets the following statuses:

Status	Description
input	The card assignee has a question requiring an answer before the work can continue.
review	The card assignee requests a subject-matter expert’s feedback on the work, most commonly represented as a pull request.

Best practices

Create sub-tasks 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 status update and leave a comment to the person best qualified to answer your query using Add update.
• Create a new card as a sub-task, set its status to sprint, and assign it to the appropriate person.

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

• If you have several blocking issues, each can be reflected on and tracked independently through a different sub-task.
• The sub-task remains on the assignee’s radar because it is visible on the associated assignee’s dashboard.
• The sub-task can be assigned to a different person if the original assignee is unavailable.

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

Avoid extending an active card’s requirements

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

• Create a new independent card
• Create a sub-task under the existing card

The benefits of creating a new card or sub-task 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