README: Document how this tech tree works
This commit is contained in:
parent
c1936c7ed2
commit
7762dbe80f
134
README.md
134
README.md
|
|
@ -3,9 +3,143 @@ FAFO Technology Tree
|
|||
This repository tracks our "technology tree" — the steps towards our
|
||||
overarching goals.
|
||||
|
||||
A description of how this tech tree works can be found below. See
|
||||
[Working with the Tech Tree](#working-with-the-tech-tree).
|
||||
|
||||
## Full Technology Tree
|
||||
Below, you can see the full technology tree. The issues in this repository
|
||||
track the elements it contains. For better overview, check each issue for its
|
||||
relevant subtree.
|
||||
|
||||
|
||||
|
||||
## Working with the Tech Tree
|
||||
Fundamentally, the tech tree is built from the issues in this repository and
|
||||
their interdependencies. For elements to be reached, create new issues and
|
||||
select one of the `Type/###` labels to declare what kind it is:
|
||||
|
||||
- Type/**Equipment** 🔬 — A piece of machinery that we need to acquire or get
|
||||
running. Mainly things that can be bought instead of built.
|
||||
|
||||
- Type/**Process** ⚗️ — A process we need to achieve. This means we need to
|
||||
become able to perform this process reliably.
|
||||
|
||||
- Type/**Development** 🔩 — A device, software, or other thing we need to develop.
|
||||
This is _engineering_ work; making use of existing knowledge to build
|
||||
something useful.
|
||||
|
||||
- Type/**Research** 🧪 — A topic that we can or must research to unlock future
|
||||
capabilities. In contrast to _Development_ elements, we cannot make use of
|
||||
prior art here. So less engineering and more _science_.
|
||||
|
||||
#### Dependencies
|
||||
Once created, add dependencies between issues to model their relationships.
|
||||
The CI of this repository will automatically update the tech tree accordingly.
|
||||
In addition, each issue gets a partial representation of the subtree of
|
||||
elements directly related to it. You can quickly see what is still missing to
|
||||
achieve a particular element. And also what next steps will be unlocked once
|
||||
an element has been achieved.
|
||||
|
||||
There are no distinct types of dependencies. This was a choice in the name of
|
||||
keeping the model simple. All dependencies are hard requirements. But also
|
||||
check the next section on more thoughts about this...
|
||||
|
||||
#### Modelling Approach
|
||||
Finding the right balance between model complexity and expressiveness is
|
||||
tricky. Following are some guidelines for adding elements to this tech tree.
|
||||
|
||||
All elements should have a few fundamental properties, to keep the model consistent:
|
||||
|
||||
- Elements shall have a **clear and unambiguous acceptance criterion**. If
|
||||
necessary, this can be elaborated on in the issue body. "SEM Imaging" leaves
|
||||
open what scale we can image reliably. It may be sensible to add multiple
|
||||
elements to model progress in such a domain.
|
||||
|
||||
- Elements shall be **actionable**, in the sense that someone can put in effort to
|
||||
achieve them. Having a good acceptance criterion does most of the heavy
|
||||
lifting here.
|
||||
|
||||
- Elements shall be **necessary** for our bigger visions. Ultimate elements
|
||||
(elements that nothing depends on) should get special consideration in this
|
||||
regard. If you have visions of your own, it is of course fine to make an
|
||||
ultimate element for them.
|
||||
|
||||
- Elements shall have a scope/granularity size that is appropriate for tracking
|
||||
progress. We will need to figure this out as we go.
|
||||
|
||||
Generally, our tech tree is a living object. It should be updated as we figure
|
||||
out more elements to be tracked and their dependencies.
|
||||
|
||||
One topic of particular interest are "path choices". We can either use
|
||||
technology A or technology B to achieve element C:
|
||||
|
||||
```mermaid
|
||||
flowchart BT
|
||||
classDef eoi fill:#fff, stroke:#000;
|
||||
classDef dependant fill:#fff, stroke:#888, color:#888;
|
||||
classDef dep_missing fill:#fcc, stroke:#800;
|
||||
classDef dep_assigned fill:#ffa, stroke:#a50;
|
||||
classDef dep_completed fill:#afa, stroke:#080;
|
||||
0:::dep_missing
|
||||
0["#1 | MISSING\n<i>Process</i>\n<b>Technology A</b>"]
|
||||
1:::dep_completed
|
||||
1["#2 | COMPLETED\n<i>Process</i>\n<b>Technology B</b>"]
|
||||
2:::eoi
|
||||
2["#3 | MISSING\n<i>Process</i>\n<b>Element C</b>"]
|
||||
2 --> 0
|
||||
2 --> 1
|
||||
```
|
||||
|
||||
Dependencies cannot express such choices. Instead, please follow this approach:
|
||||
|
||||
- Initially, all potential path choice dependencies are added. The issue body
|
||||
shall document the choice options and implications.
|
||||
|
||||
- When we get closer to the element of interest, we make the choice of what
|
||||
path to pursue. At this time, the other dependencies are dropped. The
|
||||
tech-tree now only documents the path choice we have made.
|
||||
|
||||
Another situation we will encounter is the need to use generic equipment for
|
||||
specific purposes. If the specific purpose is non-trivial, it shall be
|
||||
modelled as an intermediate _Process_ element in-between:
|
||||
|
||||
```mermaid
|
||||
flowchart BT
|
||||
classDef eoi fill:#fff, stroke:#000;
|
||||
classDef dependant fill:#fff, stroke:#888, color:#888;
|
||||
classDef dep_missing fill:#fcc, stroke:#800;
|
||||
classDef dep_assigned fill:#ffa, stroke:#a50;
|
||||
classDef dep_completed fill:#afa, stroke:#080;
|
||||
0:::dep_missing
|
||||
0["#2 | MISSING\n<i>Process</i>\n<b>Processing X using machine A</b>"]
|
||||
1:::dep_completed
|
||||
1["#1 | COMPLETED\n<i>Equipment</i>\n<b>Generic Machine A</b>"]
|
||||
2:::eoi
|
||||
2["#3 | MISSING\n<i>Process</i>\n<b>Element C</b>"]
|
||||
2 --> 0
|
||||
0 --> 1
|
||||
```
|
||||
|
||||
|
||||
|
||||
#### Element Status
|
||||
The status of each element is determined as follows:
|
||||
|
||||
- **MISSING** when the element has not yet been achieved.
|
||||
- **ASSIGNED** when the issue has been assigned to someone. This means we are making progress!
|
||||
- **COMPLETED** when the issue gets closed. Achievement unlocked!
|
||||
|
||||
#### Important notes
|
||||
There are a few gotchas that you should be aware of:
|
||||
|
||||
- The CI will not automatically update when changing dependencies,
|
||||
unfortunately. You can force a trigger by editing the issue body or quickly
|
||||
adding and then removing the `Stale` label.
|
||||
|
||||
- You cannot add dependencies on closed issues via the Forgejo interface. To
|
||||
model such dependencies, temporarily reopen the dependency issue and close it
|
||||
again after adding the relationship.
|
||||
|
||||
- Issues that should no longer be a part of the techtree should either be
|
||||
deleted (looses all tracking) or they can be made inert by removing the
|
||||
`Type/###` label.
|
||||
|
|
|
|||
Loading…
Reference in a new issue