Keep a Technology Atlas
A technology atlas is a set of HELIX documents about technologies instead of one product: what each technology can and cannot do, how several compare on stated criteria, and what a team advises and why. This page is for a team that already uses HELIX and wants to keep that knowledge as governed, checkable documents. After reading it, you can set up an atlas flow, write an assessment and a position paper that the validator checks, and pin the sources a published document rests on.
What the profile changes
A flow scope, declared in .helix.yml, can name a profile. A profile selects
which artifact types the flow uses, where they live, which link kinds are
allowed, and how strictly each validation tier checks them. A flow with no
profile behaves as before, so nothing changes for a software-delivery flow.
flows:
- id: atlas
profile: technology-atlas
root: knowledge/The technology-atlas profile uses seven types:
| Type | Holds | Lives in |
|---|---|---|
component-profile with scope: reusable | What the public record says about one technology, with no project or verdict | technology/ |
technology-assessment | A comparison of technologies on stated criteria, with findings and no recommendation | assessments/ |
position-paper | An argued position, or advised stances, for an audience | positions/ |
tech-spike with scope: reusable | A measurement that answers one open question of a brief, which anyone can rerun | spikes/ |
decision-brief | A recommendation for one named context | decisions/ |
adr | A decision record | decisions/ |
deliverable | A document issued to an audience, with its sources pinned | publications/ |
Knowledge in an atlas is advisory. A document that cites an atlas document does
not take orders from it, and a link that claims governing authority is a
blocking finding under this profile.
Assess a practice
Some subjects have no product at their center: continuous integration is one. A
technology-assessment with scope: practice in its frontmatter covers such a
practice. It rates no technology, so it has no Criteria, Technologies,
Comparison, or Evidence section. It keeps Scope, Findings grouped by reader,
and Contradictions and Gaps, and it closes with numbered Sources. Where a
technology assessment already covers the subject, explain the practice there,
so a reader is handed one document per subject.
Close a brief with reader views
A technology brief (component-profile with scope: reusable) closes with a
## Views section, placed before Confidence. It has four headings, one for each
reader: Risk & Compliance, Finance, IT Operations, and Apps Dev. Under each
heading, write one sentence that answers that reader’s first question, then name
the sections that carry the facts.
The sentence sums up what those sections already say. A fact and its source stay
in the section that states them. A view the brief does not cover says
Not applicable, with the reason, or Not researched. Keep all four headings.
validate-instance.py blocks a Views section that drops a heading or leaves one
empty. A brief with no Views section was written before the section existed. It
gets a warning at both tiers and still publishes, so you can add the section at
the brief’s next revision.
Write an assessment with ratings as data
An assessment can keep its criteria and ratings in front matter, so the tables a reader sees are generated from data and cannot drift from it.
- Create
criteria.ymlin the flow root. Each entry has anid, alabel, adefinition, and theconcernit serves ornone. One criterion is one entry shared by every assessment. - In the assessment, add an
assessment:block besideddx:. It lists the criterion ids, the subjects (each a technology brief and the name to show), and a rating for every criterion and subject. A rating is afindingor a statedgapsuch asNot published. - Link each subject in
ddx.linksasevaluatesorsupported_by. - Run
assessment-tables.py --writeon the file. It rewrites the Criteria and Comparison tables from the block. Without--writeit reports a table that differs from its data, which makes it usable as a CI check. - Run
validate-instance.pyon the file. It blocks an unknown criterion, a subject that is not linked, and a pair with no rating or gap.
Findings and gaps are one line each, because each fills one table cell.
A flow can also keep a views.yml beside criteria.yml: a views: list that
names the readers a criterion answers, each entry with an id and a label. A
criterion can then carry view:, with one id or a list of ids. The validator
blocks a view: that views.yml does not list. Without a views.yml, it does
not check view:.
Record stances in a position paper
A position paper can record what the team advises as a recommendations: list.
Each entry names a subject and a context, and takes one stance: recommended,
conditional, watch, or avoid. It also gives a rationale and the
assessments it rests on, with the criteria it cites. A conditional stance states
its conditions.
Each entry carries since and review_by dates. It reads as proposed until it
also records approved_by and approved_on, together. The first table under
## Recommendations is generated from the list by assessment-tables.py.
Only a position paper can carry a stance. Putting recommendations: on a brief
or an assessment is a blocking finding, which keeps what is documented apart
from what is advised.
Weigh criteria in a position paper
A position paper can also say how much each criterion counts, in a weights:
list beside recommendations:. Each entry names a criterion, gives a weight of
decisive, important, or minor, and states the reason in one line.
weights:
- criterion: licence-cost
weight: decisive
reason: The budget has no room for a per-seat fee.The criterion must be an id in criteria.yml, and an assessment the paper links
as supported_by must have a finding for it, not a gap. The validator reads that
assessment from the flow as it stands today, not at its pinned revision.
assessment-tables.py writes the first table under ## Decision Criteria from
the list.
A weight is a judgment, so only a position paper can carry one. A weights:
list on an assessment, a weight inside an assessment: block, and a weight
in criteria.yml are each a blocking finding. The scale has three steps and no
numbers, because a number would claim more precision than the evidence has.
A position paper also states when the other option wins. Under ## Limits of the Position, add a table with the columns Condition, Option that wins, and
Evidence, and at least one row. The validator blocks a table there that has other
columns or no rows. A paper with no table in that section was written before the
table existed. It gets a warning at both tiers and still publishes, so you can
add the table at the paper’s next revision.
Add a ## Transition Path section only when the position displaces something
already in use.
Answer an open question with a spike
A brief routes what the public record cannot answer to a spike. In an atlas, the
spike is a tech-spike with scope: reusable, stored as
spikes/TS-{number}-{subject}.md. It differs from a project’s spike in four
ways:
- It runs on public inputs only, so anyone can rerun it. A spike that needs a client’s systems or data belongs in that client’s own flow.
- It records a Test Setup (version, environment, settings, data, and date) and a Reproduction section, with the scripts kept in the repository.
- It has a Views Affected table that says which reader’s answer the result changes.
- It has no Recommendations section. The validator blocks a
**RECOMMENDATION**:line at this scope.
The spike links the brief it tests and names the open question by number:
links:
- {id: component-profile-postgresql-reusable, kind: answers, question: 2, rev: git:<commit>}An answers link without a question number is a blocking finding. The
validator does not open the brief to confirm that the question exists.
At its next revision, the brief cites the spike as a source of class measured.
A measured source counts as independent corroboration in the brief’s Confidence
grade, but only for the configuration the spike ran. A grade that rests on a
measured source says so and names that configuration.
Record where a figure comes from
A figure can end with an attribute list that says where it came from:
| Support window | Five years per major version | {basis=published accessed=2026-11-06 source="postgresql.org/support/versioning"} |basis is published when the maker states it, third-party when someone else
estimated it, or not-published when the record was searched and the figure is
absent. Unless the basis is not-published, the attribute list needs a source
and an accessed date in YYYY-MM-DD form. validate-instance.py checks every
attribute list that names one of these fields, and skips code and comments.
This notation is HELIX’s own. It is not part of DITA or its Markdown profiles, and a DITA processor drops it.
Use short keys for technologies
Ratings repeat a technology’s document id in every row, and ids are long. A
keys.yml in the flow root maps a short name to a document id:
keys:
pg: component-profile-postgresql-reusableA subject, a rating’s subject, a recommendation’s subject, and a based_on
assessment can then use pg. A document that uses a key also records what it
resolved to in a top-level keys: mapping. If keys.yml is later edited to
point pg somewhere else, every document that used it fails validation until
someone reads what it cites and updates the record. A key is only an alias:
ddx.links keep the full id and the pinned revision.
Pin sources before publishing
A published document must be reproducible from the sources it cited. Under the
publish tier, every evaluates, supported_by, and informed_by link needs a
rev: git:<commit> or sha256:<hex>. In a position paper, each assessment
named in based_on needs one too.
- Commit the sources, then run
pin-sources.py pinon the document. It writes the commit each unpinned link last changed in. - Run
validate-instance.py --tier publishon the document. - Later, run
pin-sources.py checkto see whether a source has changed since the pin. A changed source never rewrites the document: it keeps the content it was written against.
pin-sources.py pin needs each link written on several lines, with id: and
kind: on separate lines.
What is not checked
The validator reads one document at a time. It does not check that a cited assessment links the recommended technology, that the assessment has findings for the criteria a recommendation cites (it does check this for a weight), or that two papers do not give the same technology conflicting stances in one context. Check those by hand until a graph-level check exists. A link that points at another graph is recorded and pinned but not fetched, so the runtime or your own tooling resolves it.
Next steps
- Read Multiple Flows and Microsites for how flow scopes pick an owner.
- Browse Artifact Types for the briefs, assessments, and papers used here.
- See the release notes for the versions that added each piece.