Skip to content

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:

TypeHoldsLives in
component-profile with scope: reusableWhat the public record says about one technology, with no project or verdicttechnology/
technology-assessmentA comparison of technologies on stated criteria, with findings and no recommendationassessments/
position-paperAn argued position, or advised stances, for an audiencepositions/
tech-spike with scope: reusableA measurement that answers one open question of a brief, which anyone can rerunspikes/
decision-briefA recommendation for one named contextdecisions/
adrA decision recorddecisions/
deliverableA document issued to an audience, with its sources pinnedpublications/

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.

  1. Create criteria.yml in the flow root. Each entry has an id, a label, a definition, and the concern it serves or none. One criterion is one entry shared by every assessment.
  2. In the assessment, add an assessment: block beside ddx:. 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 a finding or a stated gap such as Not published.
  3. Link each subject in ddx.links as evaluates or supported_by.
  4. Run assessment-tables.py --write on the file. It rewrites the Criteria and Comparison tables from the block. Without --write it reports a table that differs from its data, which makes it usable as a CI check.
  5. Run validate-instance.py on 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-reusable

A 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.

  1. Commit the sources, then run pin-sources.py pin on the document. It writes the commit each unpinned link last changed in.
  2. Run validate-instance.py --tier publish on the document.
  3. Later, run pin-sources.py check to 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