Skip to main content

On Keeping Task Descriptions Up to Date

· 3 min read

Context​

In software engineering, we often encounter work that is repetitive in nature. Examples of such tasks include setting up a new project, conducting a series of manual tests, or making a new release. While some tasks can be automated, reducing them to a mere click of a button or execution of a script, others are more complex and demand careful attention during their execution. Given that these tasks may not always be performed by the same individual, it's crucial to determine how to ensure correct execution every time.

Problem​

Here are several issues that can arise when tasks are poorly managed:

  • The task may not be executed correctly.
  • Completion of the task may take longer than anticipated.
  • The task may become frustrating to execute.
  • The task may not be executed at all.

Solution(?)​

A straightforward solution to this problem is to maintain well-documented tasks. Such documentation should detail the task comprehensively, including steps for execution, the anticipated outcome, and, if applicable, some troubleshooting guidance. To ensure the documentation remains relevant, it is essential to:

  • Ensure the documentation is easily accessible (i.e., not buried and subsequently forgotten).
  • Make the documentation simple to update (ideally without requiring approval).

Documenting tasks in the location where they are defined and assigned appears to be a viable strategy. The issue/ticket description often serves as the first and possibly the last reference point when someone is assigned a task. It is readily updateable if, while following the instructions, someone identifies an error or a more efficient method. A critical feature of this approach is the ability to clone the issue/ticket, facilitating the future repetition of the task.

However, this method has its limitations:

  • When a task is too complex to be fully described within a single issue/ticket, it can render the issue/ticket less effective due to a level of indirection to the actual documentation. Similarly, if a task evolves (e.g., changes in expectations or implementation), the issue/ticket may become outdated as discussions shift to the place of change (codebase) or instant messaging platforms.
  • Maintaining synchronized information across tasks can be challenging, especially if a task shares a prerequisite setup with several others. It becomes difficult to update all relevant tasks en masse upon recognizing a necessary change in setup.
  • A task may need to be necessarily brief if it is part of a larger project, thus lacking comprehensive information. In such cases, separate documentation may be required to provide a high-level overview of all tasks.
  • Typically, task systems do not offer the full feature set of a documentation system, such as the ability to include inline comments or facilitate real-time collaboration.

So, what's the best way to keep task descriptions up to date...?