Since February a majority of the population has had to make a transition from working in an office among their co-workers to working remotely. For some, this transition has not been easy. When making a drastic change in how a company operates there can be many missteps in communication that create gaps of knowledge which require extra (wasted) time from multiple people and teams.

For the last 10 years I have worked as a developer within various organizations that have been 100% in-person, 100% remote, or a mix of the two. In all of these scenarios it involved working with other organizations that operated in either the same or opposite ways as the one I worked for. This presented many challenges along the way, which overtime has allowed me to arm myself with a great skill-set in being able to communicate effectively and succinctly, but in a way that leaves little to no open-ended questions for all parties involved.

Now, most of this knowledge comes from either being a developer or managing developers and projects, but these tips and suggestions do not stop there. They can be be translated to just about any type of collaboration among peers in a company, clients, and 3rd party vendors.

In the examples below I will be using ticketing systems (like Jira) to demonstrate what you can do with these ideas. If you’re not using a ticketing system in your workflow, I would strongly consider it. It’s not a requirement to adopt some of what I will discuss below, but it will greatly strengthen the awareness your team has on all fronts. For reference, my ticketing system of choice is Jira.

Jira is a powerful ticketing system and a great tool for teams. There have been several times in the past where I was on a project with a team who had Jira and would create tasks, but were not using it to its full power, and only filling in titles and vague short descriptions. This is like buying a 4-post lift for your garage but only using it to change your oil.

To take full advantage of a ticketing system your team needs to have a clear and documented definition of what’s required. This not only helps everyone on a team, but helps keep them accountable for their work. Getting started should begin with defining what “ready” means for a task.

Definition of “Ready”

The key to effective communication is to have a clear definition of what is expected of everyone on your team. When a task is being defined it should meet the definition of “ready” before it is passed off to whoever is going to be working on it. Tasks that meet the definition of “ready”, mean that it is actionable by anyone on the team who is qualified.

While a task may not realistically be able to have all needed information from the start, they should contain enough information for a developer to start the work or at least ask further questions on what the task needs to get started. Essentially there should be enough detail in a “ready” task to make track-able progress.

A good measure for this would be: that if after 15 minutes of reading or reviewing a task, the assignee should be able to move forward on it. If that is not the case, then the task is not ready, and a manager or team lead should take it back for refinement.

It is largely up to the team lead and/or project manager to ensure that tasks are ready for assignment.

These points are what I would consider to be the bare minimum for a “ready” task

  1. The task should be categorized. In the development world this is usually a feature, bug, story, or epic.

  2. The task is prioritized. This will vary based on your company or project workflow. In an agile scenario, the task should be placed in a sprint or backlog. A task should ALWAYS have a prioritization level set (lowest, lower, low, medium, high, higher, highest).

  3. The contents of the task contain several critical points:
    – A descriptive yet succinct title
    – A full description of what the task entails. If this were a feature it would contain information about the feature, and if it were a bug it would describe the problem that needs to be solved. Ideally the description would also include the “why”.
    – A set of acceptance criteria. This is the most important piece of information for everyone to be aware of. Acceptance Criteria are a bulleted list of points that, once achieved, will mark that this task is in a “complete” state, and ready for review.
    – An estimate. Now this is not always necessary, but if a task is being billed for hourly or has a deadline, then an estimate should be added. This could be in hours, days, weeks, or even story points. Estimates greatly help with prioritization.

  4. If there is additional information that applies to the task and is helpful for either the person working on the task, a client/vendor, or to provide further documentation, then it should be added to the task as:
    – Notes – A bulleted listed of additional notes to account for information that may not necessary pertain to main goal of the task, but are considerations that should be made while working on the task.
    – Examples – Past examples or external documentation that can help save time on the duration of the task.
    – Links – Internal and external links that are not notes or examples but still helpful.
    – Steps to reproduce. This is something I do for bug tickets, but if there is a problem to solve, the steps to reproduce the issue can always be helpful regardless of if this is for a development task or not.

Those points are generally very helpful in keeping people on task, but no one is perfect, and there will occasionally be missing pieces of information. So having this all defined in a document (I use Confluence for this) will allow you and your team to always go back and reference to ensure they are meeting requirements.

What if you are assigned a task that is not “ready”?

It is up to the team lead and/or project manager to ensure that tasks are actionable. If someone is assigned a task that does not meet the minimum amount of information to be defined as ready, then they should inform their lead or manager what updates are needed for the ticket before they can get started on it.

Here are some examples of tasks (in this case Jira tickets) that meet the definition of “ready”:

Notice how the description is clear but not too verbose. The description gives a reason as to why this ticket has been created and the acceptance criteria gives a list of items that will allow the developer to check off items as they complete them, so they know exactly what is expected for this ticket.

In this example you can see that there is more information given. In addition to the example code, a link to an external resource was provided along with a note about a future update that will be incorporated to this. So the developer has a sense of how they should build the plugin from the start instead of possibly having to refactor further later on. Also included is that this ticket is blocked by the task in the above example. So the developer knows they cannot begin work on this ticket until the blocking task is complete.

Task Workflows

Workflows are critical to give information about the status of tasks. The workflow you choose will vary greatly on your project or team requirements. For development projects I like to use this general set of workflow statuses:
Backlog > To Do > In Progress > In Review > QA > UAT > Done

  1. Backlog means a task is identified, but not yet refined and/or prioritized.
  2. To Do means a task has been prioritized. At this point the task may or may not be refined and assigned out. It is during this point that a task would be refined and assigned.
  3. In Progress means a task has been prioritized, assigned, and is in development.
  4. In Review means that either development on the task is complete and it is open for review (ie a pull request or dev verification), it failed QA or UAT, or needs to be further refined. Within this status a task may pass several hands, so task updates are very important (see below).
  5. QA (Quality Assurance) means the task has passed review and verification and can now be tested. At this point a development task would have a set of testing instructions so whoever is designated for QA can quickly pass or fail the task.
  6. UAT means the task has passed QA and is now ready for User Acceptance Testing. This status can vary depending on the type of project, but usually a lead or manager will own this task again once it reaches this point.
  7. Done means the task is 100% complete (See Definition of “Done” below). At this point a development task would be deployed.

Here’s an example of what a task workflow looks like on a Kanban board:

You can see that tasks will fit into one of the 6 given categories, and as they progress, the tasks are dragged to their appropriate workflow status column.

Task Updates

Once any progress has been made on a task or any stopping point is reached a comment should be added that goes over all of the work that has been completed so far (or since the last update) and what the next steps for that task are. In the case of a development task, this would include any links to open pull requests or work-in-progress branches.

Updates should be bullet points and provide detailed explanations of the problem and/or solution and other work that was completed.

Next steps should include what the next actions for the task are. For a development task this could a pull request that needs review, dev verification, adding testing instructions, sending/passing/failing QA or UAT, or being deployed.

Here are some examples of task updates:

Take a look at each of these task updates (in the form of ticket comments). Each one gives a clear overview of what has been completed on the task and what is to be done next.

Formatting

One thing you may have noticed from those examples is how clean and easy to ready all of the information is. Formatting for both ticket descriptions and comments is important for readability and consistency.

A readable and consistent format not only helps everyone better understand context around a ticket and its current and past progress, but conveys a sense organization and attentiveness to clients, superiors, and subordinates that show dedication and sustainability as a company.

Generally you will want to have different fields for different projects/boards. When provided, fields for items like “acceptance criteria” or “testing instructions” should be used.

In cases where we only have a “Description” field, the following format should be used:

  • Within the Description there should be an H2 for each major section
    • Description
      • Descriptions can be separated out with minor sections using H3
      • Text in descriptions should be “Normal text”
    • Acceptance Criteria
      • Acceptance Criteria should be a bulleted list of points to hit for the ticket
    • Notes
      • Notes can be bullets or “Normal text” depending on the context
    • Examples
      • Code examples should be formatted using the {code} //code goes here {code} format
    • Links
      • Links should be a bulleted list of external or internal links
    • Steps to Reproduce
      • Each step should be a numbered step that starts with one of the following phrases:
        • Go here:
        • Do this:
        • You should see this:
    • Testing instructions
      • Each step should be a numbered step
        • Go here:
        • Do this:
        • You should see this:

The most important part of formatting is to make sure its consistent. Have your formatting documented somewhere that is easily referenced.

Definition of “Done”

Once a task passes QA or UAT (testing phases) it can be queued for a future deployment. A this point the task’s acceptance criteria should be met and approved by QA and UAT workflows.

Once the task is deployed it should be marked as “Done” or “Complete” and cleared from your board.

Summary

With these set of suggestions and tools, hopefully you can help implement a sustainable and clear solution to filling in the gaps while working remotely.

And remember, the key points here are:
1. Agree to format and workflows that make sense for your application.
2. Document your agreed upon set of criteria.
3. Enforce and remind others to use these tools up to the spec that was defined.