README: Document how this tech tree works

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.
 
 ![FAFO Tech Tree](https://git.fa-fo.de/rahix/techtree-poc/raw/branch/render/techtree.svg)
+
+## 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.