Learn · Obsidian for researchers

How to build a qualitative codebook in Obsidian (free, step by step)

A codebook is what makes your coding consistent — for a second coder, for a reviewer, and for you six months from now. You can build a disciplined one in Obsidian with nothing but plain Markdown: one note per code, a fixed structure, and a small Dataview table that watches the whole set. Free, local, and future-proof.

What a codebook entry needs

A code is a short label you attach to a unit of meaning in your data. A codebook makes that label usable by someone other than you, on a day other than today. The minimum that achieves is four things: a definition, an inclusion rule (what must be present to apply it), an exclusion rule (the near-misses, and which code takes over), and an anchor example — one real excerpt that is unmistakably this code. Add a revision history and you can defend every change in your methods section.

Step 1 — one note per code, with a fixed shape

Make a folder, Codebook/, and one note per code. Give every note the same structure so they stay comparable. The YAML block at the top (the --- fenced section, called frontmatter) is what a Dataview table will read later.

---
type: codebook-entry
code: waiting-for-results
status: stable        # candidate / stable / merged / retired
created: 2026-07-09
last_revised: 2026-07-09
---

# Code — waiting-for-results

## Definition
The bounded period between a test and its result, experienced
as its own thing: its length, its open-endedness, what it does
to the person.

## Use when (inclusion)
Talk about the days between scan and answer — phone-watching,
sleepless nights over a pending report, the wish for a fixed date.

## Do NOT use when (exclusion)
The long rhythm between visits (use [[Code — living-scan-to-scan]])
or preferences about how results arrive (use [[Code — information-on-own-terms]]).

## Anchor example
> "Five days, once it was nine days. Nine days!"
> — P01 (I01-e002)

## Revision history
| Date | Change | Reason |
|------|--------|--------|
| 2026-07-09 | created | first appearance |

The [[double-bracket]] links in the exclusion section matter: they connect each code to its neighbours, so the boundaries between codes become visible in the graph, not just described in prose.

Step 2 — a dashboard that watches the whole set

Install the Dataview community plugin (Settings → Community plugins). Then a single note can show your entire codebook as a live table that updates itself as you add or revise codes:

```dataview
TABLE code, status, last_revised
FROM "Codebook"
WHERE type = "codebook-entry"
SORT status ASC, code ASC
```

Now you can see at a glance which codes are still candidate, which are stable, and which have not been revised since you last sharpened your definitions. A second query filtered to status = "candidate" becomes your to-do list.

Step 3 — keep merges and splits in the history

Codebooks change as you code — that is not drift to hide, it is analysis to record. When two codes keep overlapping and you merge them, do not delete the loser: set its status: merged, add a merged_into: field, and write the reason in its revision history. When one code is pulling in two directions and you split it, record that too. A reviewer who can read why a code changed trusts the coding far more than one shown a tidy final list with no history.

Three mistakes that make a codebook fail

• Definitions too broad to exclude anything. If a code could apply to half your excerpts, it is not a code, it is a topic. A good test: if you cannot write the "do not use when" section, the definition is not sharp enough yet.
• No exclusion rules. Inclusion tells you where a code fits; exclusion tells you where it stops and which neighbour takes over. Without it, two coders — or you on two different days — will apply overlapping codes inconsistently, and no one will be able to see why.
• Deleting codes you merged or dropped. A codebook's history is evidence you were thinking. Retire codes with a status and a reason; never erase them. The tidy final list with no history is exactly what makes a reviewer suspicious.

Why plain Markdown, not dedicated software

NVivo, ATLAS.ti, and MAXQDA hold your codebook in a proprietary project file. Obsidian holds it as ordinary text files you own, that open in any editor, that version-control cleanly, and that no licence expiry can lock you out of. For a codebook — a document you may need to produce years later for a reviewer or a replication — that durability is not a minor convenience. It is the point.

Read next

Before the codebook: AI-assisted coding with human review. Alongside it: Obsidian Canvas as an evidence map and the Obsidian for researchers FAQ.