Skip to content

Many sources, one context graph

This knowledge base started as a way to keep studio gear straight. Its real subject turned out to be a common problem: content from many authors, in many formats, that uses different words for the same things, and that has to be usable as one body of knowledge.

The sources here are 66 documents from 26 manufacturers (35 user manuals, 12 product pages, 11 quick starts, 5 original design manuals, 3 datasheets; 5 of them scanned and OCR'd), plus three apps that each have code and documentation of their own: Documentation site, Knowledge-base build tools, Patchbay. The documentation site is treated as an app like the others. It has content, build code and data dependencies, and it publishes another app's user guide. Nothing here is rewritten to force the sources to agree. Each source keeps its own words, and a shared vocabulary maps those words onto one set of concepts.

Many sources, one context graphManuals from many manufacturers, app documentation, code comments and UI labels are all read with one label matcher into a shared vocabulary of concepts, which serves search, grounded answers, change impact and gap analysis.66 manuals26 manufacturers, 5 formats65 app doc sections3 apps, incl. the docs site28 code filesdocstrings and comments34 UI labelswhat users clickShared vocabulary108 concepts, 162 labels55 used by manuals and appsUSES_TERM 1,704 edgesSearch and navigationGrounded answers (cite the sources)Change impact across appsContent gaps both waysSources keep their own words; the vocabulary maps every word to one concept, so every use sees one graph.

Every number is counted from the committed graph files on each build.

The layers, and how they join

Layer What it links Built by Checked by
Inventory and wiring gear, makers, cables, case positions, power hand-kept YAML validators; graph questions q1-q6
Manuals 66 documents, 1,930 sections, provenance per section convert_manual.py coverage checks, strict build
Terminology 108 concepts, 162 labels, typed relations TERMS.yaml, build_terms.py taxonomy rules; q7-q9
Code and docs 3 apps, 28 code files, 334 functions, 65 doc sections build_code_graph.py drift checks; q10-q12
One context graph all of the above, joined build_graph.py q13-q15 below

The joins are ids that more than one source shares:

  • Terminology. A manual, a doc section, a code comment and a button label that name the same concept all get a USES_TERM edge to it (1,704 such edges). That's how a Roland manual's "sync" and the Patchbay's "Clock/Sync" legend end up next to each other.
  • Datasets. Apps that read the same file are joined through it. The three apps here share 10 datasets (for example connections.yaml, docs/manuals, graph/public/budget.json, graph/public/vertices.json).
  • Domain entities. A dataset defines or describes items and manuals, so code and docs reach the gear itself.

Asking across every source at once

  • Where is clock and sync covered: how many manuals, which sections of each app's docs, and which code?
    32 manuals; Documentation site docs: Choices the owner made that changed the outcome; Patchbay docs: Eurorack, Patching cables, Session file format, Using it; code: patchbay/tools/extract_ports.py, patchbay/web/app.js, tools/build_public.py, tools/viz_graph.py. cross: pass
  • Which words do the manufacturers use for clock and sync, and which words do our apps use?
    'clock': After Later Audio, Akai Professional, Antumbra, Arturia, Behringer, Cosmotronic, Cre8audio, Donner, Dreadbox, E-mu Systems, Electro-Harmonix, Elektron, Intellijel, Jake's Custom Shop, Korg, Roland, Sonicware, Tiptop Audio, Yamaha; 'clock pulse': Arturia, Electro-Harmonix, Korg; 'din sync': Arturia, Elektron; 'midi clock': Akai Professional, Arturia, Behringer, Cre8audio, Dreadbox, E-mu Systems, Electro-Harmonix, Elektron, Korg, Roland, Sonicware; 'sync': After Later Audio, Akai Professional, Arturia, Behringer, Cre8audio, Donner, Dreadbox, Electro-Harmonix, Elektron, Korg, Roland, Sonicware; the apps say 'clock' (Documentation site, Knowledge-base build tools, Patchbay); the apps say 'din sync' (Patchbay); the apps say 'sync' (Patchbay). cross: pass
  • Which concepts do our apps use that no manual does, and how many manual concepts do our apps never mention?
    55 concepts are used by both the manuals and the apps; used only by the apps: none; 59 manual concepts are not mentioned by any app. cross: pass

The second answer is the whole problem in one line: five different words for one idea, spread across the manufacturers, and the apps pick up three of them. Without the shared concept those would be five unrelated strings.

Same word, different meaning

The matcher that reads the manuals reads the apps too, but some gear terms are also everyday English. In a sequencer manual fill, pattern, chain and step are features. In a developer's notes they are ordinary words ("fill the field", "a regex pattern"). So outside the manuals, 9 such concepts are not matched (accent 3, chain 6, fill 17, filter 6, pattern 18, project 10, song 8, step 17, tie 15 matches set aside). Content from different authors needs source-aware rules, not one global list, and the graph records which rule applied.

How this maps onto a larger content estate

Here In a larger organization
26 manufacturers, each with its own conventions many teams and vendors, each with its own conventions
full manuals, quick starts, datasheets, web pages, OCR'd scans wikis, doc sites, tickets, specs, slide decks, scanned records
"clock", "sync", "MIDI clock", "clock pulse" for one idea different team names for one product, process or field
TERMS.yaml: preferred and alternative labels, broader/narrower a shared vocabulary or taxonomy, owned and reviewed
three apps' code and docs graphs in one schema an application catalogue, each system publishing its slice
datasets several apps read shared data products and API contracts
gear items, manuals, placements the business entities everyone talks about
private manual sections kept out of the public graph access rules carried on every vertex and edge

What made it work

  • Map, don't rewrite. Sources keep their own words, and the vocabulary maps them to concepts. Nothing is lost, and a disagreement shows up as a fact instead of being flattened.
  • Provenance on everything. Every section, spec value and edge says where it came from and how it was derived: parsed, declared, or verified.
  • Unknown stays unknown. A missing fact is recorded as missing, never guessed. The graph questions tell "not recorded" apart from "none".
  • Documentation is an app. It has content, build code, data inputs and outputs, and it is checked like any other app.
  • Checks on every build. Drift, staleness and coverage are checked every time, so errors fail the build instead of accumulating. Every graph answer is checked against a result worked out without the graph.
  • Privacy as structure, not care. Private material has its own visibility, git-ignored files never enter the graph, and the published output is scanned before every commit.

What a consumer gets

One graph that answers "what is this, where is it described, who uses it, and what breaks if it changes?" whatever the source. The Patchbay is itself a consumer: it reads the inventory, the wiring, the MIDI plan and the drawings from this graph to pre-patch a session. Search, question-answering that cites its sources, change-impact reviews and content-gap reports are all queries over the same edges.