Document

Origin & evolution

Internal documents are as old as organisations, but software culture has argued for decades about how much to write and in what form. The agile movement's 2001 manifesto valued working software over comprehensive documentation, a corrective to specs so heavy they outlived their usefulness. The reaction overshot in places, leaving teams with too little written memory and decisions⚖️DecisionStrategyA recorded decision with context, rationale, and consequencesView reference → that lived only in people's heads.

Amazon's narrative culture pulled the other way and became the reference point for the working document. Around 2004 the company replaced presentation decks with prose memos, the six-page memo read in silence before discussion, on the argument that writing full sentences forces clearer thought than bullets allow. The document became a tool for thinking, not merely a record of it.

James Gleick's history of information argues the deeper point: writing does not merely capture📸CaptureWorkspaceA dated, hashed rendition of something already in the graph: a screenshot of a surface, a PDF of a report, an export of a canvas. The subject stays a graph node; the capture records what it looked like at one moment, and the content hash says whether it still does.View reference → thought after the fact — it is a precondition for certain kinds of reflective thought in the first place. Once knowledge is externalised in a persistent, readable form, a thinker can look back at their own reasoning, find the contradictions, and revise. By that reading, the Amazon memo is not a cultural quirk but an instance of a much older pattern: structured written records make thinking legible to the thinker.

Where the field landed is a working-doc discipline that prizes a few well-kept living documents over either extreme: enough writing to make decisions legible and durable, structured so the reader finds the reasoning, revised as understanding changes. The unresolved tension is scope. A document drifts toward becoming a published reference, or a formal deliverable, and teams that never draw those lines accumulate a sprawl of half-internal, half-external files nobody trusts.

How it works in practice

A team kicks off a quarter with a six-page strategy document: the bet, the evidence🔎EvidenceValidationData supporting or refuting a hypothesisView reference →, the risks🎲RiskComplianceA risk to the product or businessView reference →, the sequencing. It is read in the planning meeting, argued over, and amended in place. Over the next weeks it spawns sharper artefacts: a one-page memo summarising the chosen direction for leadership, meeting notes that capture what changed, a spec for the first build. When a customer-facing explanation is needed, the team does not point users at the strategy doc; it writes a separate knowledge base article📓Knowledge Base ArticleContent & KnowledgeA knowledge base articleView reference →. The internal documents stay internal and stay editable, which is what keeps them honest as the plan moves.

Document vs. its neighbours

• Knowledge base article is external, published reference written for users. A document is internal working memory written for the team. The split is audience and stability: the article is polished and stable, the document is provisional and revised. Collapsing the two is how internal half-thoughts leak to customers.
• Documentation template🖊️Documentation TemplateContent & KnowledgeA template for documentationView reference → is the empty structure a document can be poured into. The template is reusable shape; the document is a specific instance, which may use a template or none at all.
• Deliverable is a document promised to a stakeholder🧑‍💼StakeholderTeam & OrganisationA person with influence over the productView reference → as committed output, often contractual. A document is the wider category; a deliverable is a document with an owner, a recipient, and an acceptance bar attached.

In the graph

In the Unified Product Graph, a document sits in the content region as the general-purpose record. Three canonical edges place it: product_documented_in_documentProductdocumented inDocumenthierarchy and product_records_in_documentProductrecords inDocumenthierarchy tie a product's knowledge to the artefacts that hold it, and content_calendar_schedules_documentContent CalendarschedulesDocumenthierarchy lets recurring documents (the weekly memo, the quarterly strategy doc) sit on a cadence. Keeping the document distinct from the knowledge base article in the schema is what enforces the internal-versus-external line the discipline keeps blurring: the two are different nodes with different edges, so a query can always tell working memory apart from published reference.

0.34.0 adds the one thing that family could not say. document_transcludes_nodeDocumenttranscludesany entitysemantic lets a document embed a node's live value at a position in its prose, and it is polymorphic because the target set is genuinely open. The nine describe-targets include none of metric🔢MetricStrategyA unified metric that measures progress, health, or behaviour across the productView reference →, research_study🧑‍🔬Research StudyUser ResearchA planned research activityView reference →, specification📋SpecificationFoundationsA canonical open standard or specification that primitives and products conform toView reference → or architecture_decision⚖️DecisionStrategyA recorded decision with context, rationale, and consequencesView reference →, which is what most documents carrying no outbound edge at all were reaching for. The distinction from document_describes_personaDocumentdescribesPersonasemantic and its siblings is worth holding precisely. Describing is a claim about subject matter. Transcluding is a claim about rendering: a plan that transcludes a metric🔢MetricStrategyA unified metric that measures progress, health, or behaviour across the productView reference → shows whatever that metric reads today, not the number somebody typed when the sentence was written. Collapsing the two would lose the only property transclusion is bought for, which is being current by construction.

The anchor form the edge binds to already existed, is already parsed, and is published as Appendix F of the specification📋SpecificationFoundationsA canonical open standard or specification that primitives and products conform toView reference → paper: [[type:id]], with variants🆎VariantGrowthA variant in an A/B testView reference → carrying a display label, inline key-value qualifiers, a creation marker, and a cross-product target. What 0.34.0 states is the binding. An anchor appearing in the body of a document is a transclusion anchor, and a conformant parser writes the edge beside it. Anchor and edge are one fact recorded twice, so they are written together or they drift.

There is deliberately no position property on the edge. The obvious anchor_line is the most volatile value a text document has, because every insertion above moves every anchor below and nothing reports the drift. The anchor is the position, and it lives in the prose where ordinary editing moves it for free. The edge is also deliberate_only, which means a parser emits it explicitly from an anchor a person typed, and no generic pair-resolution path may infer one from the node wildcard.