Articles

How to understand a complex topic: layers instead of one giant diagram

When a topic gets complex, familiar tools give up at the same point: too many tabs, a spreadsheet with thirty sheets, a diagram that has become a tangle. Why this happens, and an idea worth borrowing from technical documentation.

· Matvey Zakharenko · 8 min read

Tabs, and more tabs

  • Learning something new, you quickly collect open tabs. Each one leads to the next question, and the main thread gets lost.
  • There is a constant fork: follow the route of the book or course, or dive into the side branch that feels important right now.
  • A spreadsheet with 20–30 sheets and cross-references stops being readable. A diagram in Miro or draw.io turns into a knot.

Everyone has the same impulse: cut away the excess to understand what is going on again.

Companies have it too, only faster

Domains, processes, artefacts and databases keep growing. Digital twins add layered graphs of entities and relations. The bottleneck shifts: producing a document, a diagram or code has become cheap, while understanding and verifying it has not. This is sometimes called comprehension debt, or cognitive debt.

Language models speed up production even more, so the gap between “made” and “understood” keeps widening. Documenting everything is impossible. What you need is the ability to look at the part that matters now without losing its links to everything else.

First hint: a wiki maintained by a model

Andrej Karpathy described the idea of an LLM Wiki: a model maintains a knowledge base by itself — it reads sources, updates pages and adds cross-references, while the raw materials are kept apart from what is synthesised from them.

The most useful thought there is to keep small, connected views built around a specific question, so you can return to the results of an analysis instead of starting over.

Second hint: how technical documentation works

Large companies stopped managing documentation as documents long ago; they manage components. That is what component content management systems — CCMS — are for:

  • one component is reused in hundreds of documents;
  • text is separated from presentation, for example with the XML-based DITA standard;
  • PDFs, web pages and help centres are all published from the same base of components;
  • when a paragraph changes, only that paragraph goes to translators;
  • version history is kept per component rather than per document.

The key idea for diagrams: change it in one place, see it everywhere the component is used.

The hypothesis: lay the graph out on sheets

  • Nodes and links are spread across several sheets, each devoted to its own part of the topic.
  • Links work both within a sheet and between nodes on different sheets.
  • One entity can live on several sheets — the same component idea as in a CCMS, only on a diagram. Its description changes once and updates everywhere.
  • Sheets can use different notations, from free-form notes to strict diagrams. PlyLoom imports diagrams from draw.io, BPMN and Obsidian Canvas.
  • A model can help find connections between materials, but a person checks the proposed links: models confuse entities, conditions and the direction of dependencies.

What it looks like in practice

Take a small coffee roastery:

  1. At first everything is on one diagram: suppliers, roasting, packaging, sales channels, money. After a couple of dozen nodes it is already hard to read: topics mix, and every new link adds crossings.
A training roastery on one plane: 26 nodes and 32 links, purchasing, production, sales and money mixed together
Step 1. The whole roastery on one plane: 26 nodes and 32 links. Neatly placed, yet purchasing, production, sales and money stand mixed together. Training data; the numbers are invented.
  1. Nodes are laid out on sheets: green-bean purchasing, production, sales, finance. Links to other sheets are shown on the frame around the sheet — one group per neighbouring sheet — so you can see where each topic continues.
The Production sheet: the process from a green-coffee lot to a bag, purchasing on the left of the frame, sales on the right, finance at the bottom
Step 2. The Production sheet holds only the process from a green-coffee lot to a bag. Purchasing, sales and finance sit on the frame with their own nodes.
  1. Spread puts production and sales side by side: you see the links between them and nothing else.
A spread of two sheets: production and sales, dashed links between the panes and the gold line of the 250 g bag
Step 3. Spread: production and sales side by side. The gold line joins the “250 g bag” on both sheets — one entity, not two copies.
  1. Stack lays all the layers over each other when you need to understand the whole structure.
A stack of four sheets as layers: purchasing, production, sales and finance, with links between the layers
Step 4. Stack: four sheets, four layers, with links running between them.
  1. Contents and Sheet overview help you find your way once there are many sheets.
Contents: the four roastery sheets, the node count of each and the number of links between them
Step 5. Contents: how many nodes each sheet has and how many links and shared nodes connect the sheets. Clicking a number on a line opens those two sheets side by side.
  1. The result can be exported to draw.io or to JSON Canvas for Obsidian.

Open questions

  • Are layers enough to cope with the complexity of modern systems?
  • Where is the line between automation and human review?
  • Can a visual tool convey the many dimensions of knowledge, or will every diagram remain a projection?

PlyLoom is an attempt to answer these questions in practice, with maps you can open, edit and check.

Try the exampleAll example maps

An earlier Russian version of this article, with discussion, was published on Habr. Screenshots are from version 0.9.1.

Read next