Skip to content

Commit 3d4c7fe

Browse files
macrogregmacrogreg
committed
Add copies of project docs
1 parent e7cda9b commit 3d4c7fe

File tree

3 files changed

+122
-2
lines changed

3 files changed

+122
-2
lines changed

‎ProjectTemplate.ReadMe.md‎

Lines changed: 113 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,113 @@
1+
**Project Tracking Template v01** is a template for a simple engineering work tracking project that can span multiple repos. The project avoids the confusion and the clunkiness around GH Issues and Millstones and includes convenient estimation automations.
2+
3+
# Key differentiators
4+
5+
## Avoid the clunkiness and the confusion around _Issues_ and Project _Work Items_
6+
7+
_Issues'_ primary purpose is (traditionally) to be a mechanism for interacting with the open source community and with a distributed Dev team.
8+
Moreover, _issues_ exist on a repository level.
9+
10+
On contrary, project _work items'_ primary purpose is to plan and track tasks.
11+
_Work items_ exists on a project level and a single project may span several repositories.
12+
Project _work items_ are managed and controlled by project leads (or whoever is responsible for planning, scheduling, prioritization, etc.) with input from the Dev team. Specific _work items_ may or may not be linked to specific _issues_, but their respective purposes are very different.
13+
14+
To keep these concepts separate and to avoid confusion, this project uses only Non-Issue Work Items on its boards (GitHub confusingly calls them "draft items", although there is nothing "drafty" or "preliminary" about them).
15+
16+
## Avoid the clunkiness around _Milestones_ by using _Mileposts_
17+
18+
_Milestones_ exist on a repository level, while projects span multiple repositories. This creates clunkiness around using milestones for tracking delivery stages in multi-repo projects. To avoid this, we use a custom field called "_Milepost_".
19+
_Mileposts_ are named `01. Moniker A` ... `99. Moniker ZZ`.
20+
21+
22+
# Estimation Strategy
23+
24+
Users estimate work items using two custom fields:
25+
- `Size`: an estimated _range_ for time/effort required to complete a work item.
26+
- `Risk`: a level of confidence that the size estimation is correct.
27+
28+
The auto-computed custom field `Days Estimate` is a _single number_ based on those inputs. It is used for planning how long multiple sequential work items will take.
29+
For that, `Days Estimate`-values of the respective work items are summed up. The result represents the estimated number of **_working_ days** required to complete the work item(s), given the respective items' risk-confidence, and assuming **_full_ and _exclusive_ concentration** on that work.
30+
31+
Details and guidance on performing estimations, and on computing and interpreting estimate values [can be found](https://github.com/macrogreg/ProjectTrackingTemplate/blob/master/README.md#estimating-work-items-and-computing-time-effort) in the below-mentioned repo.
32+
33+
### Auto-computing `Days Estimate`
34+
35+
Do _not_ manually edit the values in the `Days Estimate` field. They are _automatically_ computed as described here.
36+
37+
The script that automatically computes `Days Estimate` is located in the repo [macrogreg/ProjectTrackingTemplate](https://github.com/macrogreg/ProjectTrackingTemplate). When you use this template to create a project, you need to clone that repo, point it to your new project, and respectively configure the security tokens for project access (detailed instructions in the repo).
38+
39+
The estimation update script is triggered by a GitHub workflow that runs every 20 minutes automatically (and can also be run manually as needed). The workflow is located in the same repo.
40+
41+
42+
# Custom Fields
43+
44+
## Team
45+
46+
The _engineering team_ and/or the _general product area_ to which a work item belongs.
47+
48+
> Change/adjust the list of teams as needed after creating a new project based on this template. `X-Team` stands for cross-team.
49+
50+
Use for high-level planning: Loosely speaking, work items from different teams can be performed in parallel, while items from the same team need to be sequenced. (This is stark simplification; work across teams may still have sequential dependencies, and work within a team may still be possible to parallelize.)
51+
52+
Use in dashboard queries: Group or filter by `Team` to focus on work items related to a single engineering team or a general product area.
53+
54+
## Milepost
55+
56+
The earliest high-level project stage or release for which a work item is required.
57+
58+
Similar to the "milestone" (a built-in GitHub concept). `Milepost` is preferred over milestones, because milestones exist on a repository level, while project mileposts can span multiple repositories. Using milestones would create clunkiness and overhead in keeping milestones synchronized across repos, or when a repo is used by different projects with potentially different "stages". The additional milestone-related features (e.g. dates) are not required for nimble low-overhead planning style embraced by this project.
59+
60+
_Milepost_ items are named like `NN. Xyz`.
61+
E.g. `01. Moniker AA`, ..., `99. Moniker ZZ`.
62+
Use number prefixes for logical sorting and make sure to reserve free numbers to add milestones later. Reserve number ranges for "special" mileposts.
63+
64+
> Change/adjust the list of mileposts as needed after creating a new project based on this template.
65+
66+
## Priority
67+
68+
The priority of completing a work item within the specified scope and timeline.
69+
70+
Use `P1` (must complete), `P2` (should complete), `P3` (nice to have).
71+
Never use `P0` for project planning. `P0` indicates unplanned "drop everything else" work, like severe operational issues or newly discovered security issues.
72+
73+
> You may change/adjust the list of possible priorities as needed after creating a new project based on this template, but it is recommended to keep the default option.
74+
75+
## Story-Group
76+
77+
A specific or set of features or a specific product area that groups related work items.
78+
A particular `Story-Group` may map to a specific high-level user-story, or it may describe a group of user-stories around the same product area.
79+
A `Story-Group` can include work items from different Teams or Mileposts.
80+
81+
> Change/adjust the list of mileposts as needed after creating a new project based on this template.
82+
> Large projects may have a large, steadily growing number of Story Groups. Curate as needed.
83+
84+
## Waiting on
85+
86+
Set to a non-empty value when an item's is `Status` is `In progress`, but actual progress towards completion cannot be made.
87+
The value of the `Blocked on` field describes what specifically prevents work towards item completion.
88+
Clear this field if an item becomes unlocked again.
89+
90+
> Change/adjust the list of `Waiting on`-values as needed after creating a new project based on this template, but keep their number low and keep things simple.
91+
92+
## Size
93+
94+
An estimated number of working days required to complete a work item.
95+
See "Estimation Strategy"-section in this doc.
96+
97+
> Do NOT change/adjust the list of possible `Size`-values after creating a new project based on this template. Automation depends on them.
98+
99+
## Risk
100+
101+
A level of confidence that the `Size`-estimation is correct.
102+
See "Estimation Strategy"-section in this doc.
103+
104+
> Do NOT change/adjust the list of possible `Risk`-values after creating a new project based on this template. Automation depends on them.
105+
106+
## Days Estimate
107+
108+
> The `Days Estimate`-value is auto-computed. Do NOT edit manually.
109+
110+
A single-number estimate for how many working days a work item will actually take to complete, based on specified `Size` and `Risk`.
111+
`Days Estimate` values for multiple for items are summed up for planning how many working days are required to sequentially complete those work items.
112+
See "Estimation Strategy"-section in this doc.
113+

‎ProjectTemplate.ShortDescription.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
Simple work tracking template that avoids clunkiness around Issues and Millstones and includes convenient estimation automations. ReadMe: https://github.com/users/macrogreg/projects/3?pane=info. Companion repo: https://github.com/macrogreg/ProjectTrackingTemplate.

‎README.md‎

Lines changed: 8 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,14 @@
11
# ProjectTrackingTemplate
22

3-
This repo contains the automations required for **project "[Project Tracking Template v01](https://github.com/users/macrogreg/projects/3?pane=info)"** and for other projects based on that.
3+
This repo contains the automations required for **project "[Project Tracking Template v01](https://github.com/users/macrogreg/projects/3?pane=info)"** and for other projects based on that template.
4+
It also contains a copy of the documentation.
45

5-
When you use that template to create a new project, you must clone this repo, point it to your new target project, and configure the security tokens for your project access (details [below](#configuring-target-project-and-security-tokens)).
6+
When you use that template to create a new project, you must clone this repo, point it to your new target project using Env vars, and configure the security tokens for your new project access (instructions [below](#configuring-target-project-and-security-tokens)).
7+
8+
> #### Related resources
9+
> * [Project Template: Main View (site)](/users/macrogreg/projects/3?pane=info)
10+
> * [Project Template: Short Description (doc)](./ProjectTemplate.ShortDescription.md)
11+
> * [Project Template: ReadMe (doc)](./ProjectTemplate.ReadMe.md)
612
713

814
# Included automations

0 commit comments

Comments
 (0)