Let the knowledge graph be built by the person who knows the domain
The knowledge that truly matters in an organization usually lives in the heads of people who are not going to learn markdown. On the team of psychologists I built one of these wikis for, what needs to be recorded is years of family interviews and a deeply read library of systemic therapy. None of them should have to know what a pull request is, and I don't see that as a shortcoming on their part.
The approach I work with for these corpora is that the conversation doesn't end there. The vocabulary and the validations are designed once, up front, and from then on the writing is done by the person who knows the subject. I described the engine behind it separately in the post about the engine. What you are reading here is the other half, the one that decides whether the project is worthwhile: who writes, who reviews, and what keeps it from degrading with use.
The bottleneck isn't writing, it's structuring
An expert writes well. What they don't know —nor should they have to— is whether what they just drafted is a concept or a thesis, or whether the relationship with that other note is called "cites" or "is based on". Those are librarian questions, not clinician questions.
And when you let them choose the tag, the problem isn't that they choose badly. It's that they choose differently every Tuesday. After two hundred notes you have sixty tags, half of them synonyms, and a graph that no longer answers anything because it says sixty incompatible things at once.
The usual way out is to put a technician in the middle: the expert talks, the technician structures. It works, it's expensive, and it breaks exactly where it hurts most, because the technician can't tell whether two domain concepts are the same thing under different names. I've played that role myself in the three corpora I've built so far, so I'm talking about something that has cost me hours.
A closed vocabulary is a form, not a cage
The clinical wiki runs on nine note types and seven relationship tags. That is all an author has to decide, apart from what they want to say.
It sounds like a limitation and it's the opposite. A rich editor offers you forty formatting options and none of meaning: you can make the title bold, but you can't say that this note contradicts that one. Here it's the other way around. Formatting doesn't matter —it's markdown— and the only thing that's regulated is precisely what can be queried later.
The closed vocabulary is not there to protect the graph from the expert. It's there so the expert can write without having to ask anyone anything.
What an author actually writes
A note from that corpus looks like this. I've translated the relationship names into something readable out of context, but the structure is literal: frontmatter with the type, a # Topology section with the relationships declared one by one, and normal prose from there on.
---
type: tema
title: Pareja
---
# Topology
* **Se apoya en**: [[obras/el-arte-de-la-terapia-familiar]], [[obras/200-tareas-en-terapia-breve]]
* **Trata de**: [[conceptos/escalada-simetrica]], [[conceptos/simbiosis]]
* **Se distingue de**: [[temas/violencia-de-pareja]]
## La pareja como sistema
Escaladas simetricas, puntuaciones opuestas, simbiosis, y el lugar
del conflicto frente al de la violencia. De aqui abajo se escribe
como se escribe cualquier cosa.There's no JSON, no database, no form with twenty fields. There's a text file where the first three bullets are the ones the graph will read. The rest of the note can run for as many pages as needed.
The agent builds the scaffolding; the judgment comes from the expert
Of everything involved in adding a note, almost nothing requires knowing family therapy: creating the file in the right place, writing the frontmatter, finding out exactly what the notes it points to are called, running the validator, and opening the branch. A coding agent with access to the repository does all of that today without difficulty.
Only one thing isn't mechanical: deciding that this note is based on that work and not on the other one. There's no shortcut there, and it's exactly what the expert knows and I don't.
The division of labor falls into place on its own. The author dictates in their own language —"this bit about symmetrical escalations rests mainly on Watzlawick, and it should be kept separate from what we say about violence"— and the agent turns it into a note that complies with the vocabulary, validates it locally, and opens a pull request. The author never even sees markdown: they see the preview site that pull request publishes, and they say yes or no.
It's worth saying where this stands, because the mechanism is the new part and the rest is not. I distilled and edited the three published corpora myself, with coding agents as my tool. Putting the expert in that seat, with the agent as intermediary, is the engagement I've signed and that starts now. What is proven and in production is the layer underneath —the closed vocabulary, the validator, and the publishing gate— which is precisely the one that makes it possible to hand the keyboard to a non-technical person without crossing your fingers.
There's a reason the exchange goes through a pull request and not a web editor: a pull request is already a review mechanism, with an author, a date, discussion, and rollback. Building a custom editor would have meant doing a worse job of something that already exists.
What the machine reviews before anyone else
Every rule in the validator has a severity level that the corpus can raise or lower. Frontmatter that doesn't parse, a note without a type, and a type outside the closed set are errors. An unknown tag and a note without a title are warnings. One rule is deliberately turned off, because pointing to a note that doesn't exist yet is a legitimate way of leaving work noted down.
On top of that, each corpus sets its own gate before publishing. The clinical wiki's gate won't deploy if the graph drops below three hundred nodes or if any of the viewer's three files is missing. The public corpus's gate is this one, verbatim:
test -f public/index.html || { echo "El build no genero public/index.html"; exit 1; }
for f in public/static/explorer.html \
public/static/okf-graph.json \
public/static/okf-explorer-access.js; do
test -s "$f" || { echo "falta el asset del grafo: $f"; exit 1; }
done
nodes=$(python3 -c "import json;print(len(json.load(open('public/static/okf-graph.json'))['nodes']))")It seems like excessive distrust until it happens to you. In the clinical wiki, a bug in my parser turned bullets from the prose into typed edges nobody had declared; the resulting graph looked plausible, and what gave it away was that the tags weren't on the closed list. The full story is in the post about the engine.
That is the underlying reason you can hand the keyboard to a non-technical person: not because they won't make mistakes, but because their mistakes have somewhere to crash.
What the author gains in exchange for the discipline
The graph on the cover belongs to that corpus. The selected node is "Couple", and the card says the only thing you need to know: seven works and twenty-one incoming notes. That is already an answered question —what this team's understanding of couples rests on, and which part of their own material converges there— and no search engine answers it.
The second gain arrives the day new material comes in. okf-impact walks the graph and tells you which notes need reviewing based on what was touched. It's not magic: it's what you can compute when relationships are declared instead of inferred.
What isn't solved yet
- I haven't measured how long it takes a non-technical author to become fluent. My bet is that the curve is set by the vocabulary, not the tool, and that a set of nine types can be learned in an afternoon. It's a bet, not a data point.
- The engine is not published as a package. It's consumed as a SHA-pinned tarball and has no continuous integration of its own. The consumers do have CI; the engine doesn't. The MIT license is there, declared in the package.json and with its LICENSE file at the root.
- Designing the vocabulary is still my job. Deciding which nine types describe a domain is half the project and can't be automated. If anyone sells you otherwise, ask them for their list of types.
When it makes sense and when it doesn't
It fits if the knowledge your work rests on lives in people and not in a system, if that material has to produce decisions someone can challenge, and if there's turnover —because the day the person who knew the most leaves, what remains is what was written down.
It doesn't fit if what you need is to search inside a thousand PDFs. There are search engines for that, and they're cheaper than this. The difference lies in whether finding the document is enough for you or whether you need to know what its claims rest on.
Frequently asked questions
Does the expert have to learn git?
No, and that's the whole premise. The agent creates the branch, validates, and opens the pull request; the author reviews the result on the preview site that pull request publishes. What does have to be learned is the vocabulary: nine types and seven relationships in the clinical corpus. That can't be delegated to anyone, because it's the part contributed by the person who knows.
Isn't it faster to have a model extract the relationships from the text?
Faster, yes; auditable, no. An inferred relationship is indistinguishable from an invented one when you look at the drawn graph: it happened to me with a parser bug that inserted false edges, and nobody saw it until the tags clashed with the closed list. Relationships are declared by hand; an agent helps write the note, but what ends up in the graph was signed off by a person.
What happens if an author enters a relationship that doesn't exist?
The validator rejects it with the filename and line number, and the site doesn't get published. That's what makes open editing tolerable: the error is caught before it reaches anyone, and the author gets a concrete message instead of a silent disaster.
Who owns the corpus if we stop working together tomorrow?
You do, with no asterisks. They're markdown files in your repository, with frontmatter, in a format with a public specification (OKF, from Google Cloud). The engine that publishes them is open source on GitHub and pinned by SHA. If I disappear or the tool disappears, the knowledge can still be read with cat.
Is your critical knowledge held by people who aren't going to write technical documentation?
A professional library, a case archive, a body of judgment that today is passed on by talking. Tell me who knows and who would have to write, and I'll tell you what vocabulary I'd set up and how much work there is before the team can edit it on its own.
