Updated
Knowledge documents
The kinds of document used to plan and build a knowledge base, and the light reorganisation applied to them.
A knowledge base is built from a handful of document kinds. Some were defined only as file-name suffixes, and some overlap. This page records what each is, the problem with it, and the chosen reorganisation.
The kinds today
| Kind | What it is | Problem |
|---|---|---|
| scope | The charter, written first | None |
| toc | A pure table of contents per topic; input to article building | No front matter or template |
| toc-home | A derived view of all tables of contents | Generated; fine |
| tracker | What is built versus planned, per topic | Hand-kept, so it can drift |
| home | Generated by the view build, never hand-edited | Appears as a file in activities, which suggests it is written by hand |
| model | Defined nowhere | Overlaps design, spec and architecture |
| inventory | Seen in practice, not a defined type | Needs a definition |
The options
Write definitions and front matter for the existing kinds as they are. Smallest change, but home stays an authored kind although it is generated, tracker stays hand-kept and model stays vague.
home becomes generated only. toc stays as the first result of the Knowledge route, with a front-matter block. tracker stays as a file but is generated from the content against the toc. model is defined narrowly as how a domain is structured, its parts and how they relate. inventory gets a definition.
Every kind becomes a record in a registry with its own schema. One source of truth, but a large step before the flow is proven.
Option B aligns the knowledge kinds with the guided flow and removes the two hand-kept files that can drift. The cost is a change to the build code so the tracker is generated.
The folder structure stays
A knowledge base keeps three folders: authored content, generated views and planning. The guided flow connects an activity to them through front-matter fields rather than moving folders, because nothing indicates the structure is the problem. See Integrating documents into the knowledge base.
Part of the apparent difference between knowledge work and other work is only location: planning files live in the knowledge base's build folder, but appear as ordinary documents inside an activity.