Joel Aufrecht
2016-09-29 23:13:54 UTC
TPG is struggling with practices for having lists of sub-tasks within
Phabricator tasks. So far we have used two approaches, neither fully
satisfactory, and we are looking for approaches that solve all of the
problems with none of the drawbacks.
The most common example of this problem is a complex piece of work, e.g. an
"Epic" task, which has many subcomponents and which may take months to
complete in full. We generally create a Phabricator task to track this work
as a whole, tagged as "Epic". Then, we have two different approaches to
decomposition.
*Approach 1: Pure subtasks*
For each divisible piece of work within this Epic, we create a separate
Phabricator task as a subtask of the Epic. The Epic task itself has a brief
description. An example of this is T137479: [EPIC] Provide support to
people in design-related roles <https://phabricator.wikimedia.org/T137479>.
What works well:
- All divisible work is tracked as subtasks, so they can be properly
tracked (status is clear, responsibility is clear, history is logged, etc.)
What works poorly:
- All work must be decomposed into sub-tasks (as opposed to being left
in outline form)
- The relative order of sub-tasks cannot be modified.
- The list of subtasks is presented in the Task Graph, which is not as
familiar or legible as an indented bullet list
- Sub-tasks may have multiple parents, which is confusing to users
expecting pure trees. For example:
â*Approach 2: Manual subtask tree*
The work comprising the Epic is documented in the Phabricator Description
field as a list or tree of subcomponents, which may be either lines of text
or links to Phabricator sub-tasks. Example: T122839: A documented and
agreed upon definition of âcore workâ exists
<https://phabricator.wikimedia.org/T122839>.
What works well:
- The order of subtasks can be edited
- Small pieces of work can be documented as lines of text instead of
complete Phabricator tasks
- The work breakdown is more legible to those expecting a checklist or
tree
- Sub-tasks can be documented using the {T######} shortcut, which
auto-updates title and status.
- Changes to the Description are well-highlighted in update emails.
What works poorly:
- The subtasks in Phabricator inevitably get out of sync with the list
of subtasks in the Description.
- The status of checkboxes in the description inevitably gets out of
sync with the status of subtasks
- The history of text-only tasks in the description is not easily
accessible in the web interface.
Example:
Should we commit to Approach 1 or 2, or are there other approaches which
provide the benefits of both?
*-- Joel Aufrecht*
Team Practices Group
Wikimedia Foundation
Phabricator tasks. So far we have used two approaches, neither fully
satisfactory, and we are looking for approaches that solve all of the
problems with none of the drawbacks.
The most common example of this problem is a complex piece of work, e.g. an
"Epic" task, which has many subcomponents and which may take months to
complete in full. We generally create a Phabricator task to track this work
as a whole, tagged as "Epic". Then, we have two different approaches to
decomposition.
*Approach 1: Pure subtasks*
For each divisible piece of work within this Epic, we create a separate
Phabricator task as a subtask of the Epic. The Epic task itself has a brief
description. An example of this is T137479: [EPIC] Provide support to
people in design-related roles <https://phabricator.wikimedia.org/T137479>.
What works well:
- All divisible work is tracked as subtasks, so they can be properly
tracked (status is clear, responsibility is clear, history is logged, etc.)
What works poorly:
- All work must be decomposed into sub-tasks (as opposed to being left
in outline form)
- The relative order of sub-tasks cannot be modified.
- The list of subtasks is presented in the Task Graph, which is not as
familiar or legible as an indented bullet list
- Sub-tasks may have multiple parents, which is confusing to users
expecting pure trees. For example:
â*Approach 2: Manual subtask tree*
The work comprising the Epic is documented in the Phabricator Description
field as a list or tree of subcomponents, which may be either lines of text
or links to Phabricator sub-tasks. Example: T122839: A documented and
agreed upon definition of âcore workâ exists
<https://phabricator.wikimedia.org/T122839>.
What works well:
- The order of subtasks can be edited
- Small pieces of work can be documented as lines of text instead of
complete Phabricator tasks
- The work breakdown is more legible to those expecting a checklist or
tree
- Sub-tasks can be documented using the {T######} shortcut, which
auto-updates title and status.
- Changes to the Description are well-highlighted in update emails.
What works poorly:
- The subtasks in Phabricator inevitably get out of sync with the list
of subtasks in the Description.
- The status of checkboxes in the description inevitably gets out of
sync with the status of subtasks
- The history of text-only tasks in the description is not easily
accessible in the web interface.
Example:
Should we commit to Approach 1 or 2, or are there other approaches which
provide the benefits of both?
*-- Joel Aufrecht*
Team Practices Group
Wikimedia Foundation