CelinQ Insights · No. 75

Generate Architecture Documentation from Sparx Enterprise Architect with CelinQ

Documentation written once and never touched again describes the architecture as it was, not as it is. The only reliable fix is documentation that comes from the model whenever it is needed.

There is a specific kind of document that most architecture practices have somewhere in a shared drive: a solution architecture document, or a system description, or an application catalogue entry, produced with real care at the end of a project, formatted properly, reviewed by the right people, and then never opened again except when someone new joins the team and is pointed at it as the place to start. Six months later, the components it describes have been renamed. A year later, an interface it lists no longer exists and two new ones have taken its place. Two years later, the document is actively misleading, and everyone who has been on the project long enough knows not to trust it, but nobody has told the new starter that, so they read it anyway and build a mental model of the architecture that is quietly wrong from the first afternoon.

The odd part is that everyone involved usually knows this is happening. The architect who wrote the document knows it will start drifting the day it is filed. The new starter half-suspects the onboarding document they were handed is out of date, and hedges accordingly, cross-checking anything that matters against a colleague before relying on it. The audit reviewer, who has seen this pattern in enough organisations, treats a submitted architecture document as a starting point for questions rather than a settled account. Nobody is fooled, exactly, but everyone still spends time on documents that everyone privately expects to be somewhat wrong, because there has never been a practical alternative to writing them by hand and hoping someone remembers to keep them current.

This is not a discipline problem that better habits would fix. The underlying issue is structural: a hand-written document and a living model are two separate artefacts the moment the document is saved, and keeping two separate artefacts in step requires someone to notice every relevant model change and manually propagate it into prose, forever, for as long as the document is expected to remain trustworthy. Nobody signs up for that job explicitly. It falls, undocumented and unrewarded, into the gap between "someone should update the document" and "nobody currently owns updating the document," and it loses that contest almost every time, because the model keeps moving and the document does not move with it unless someone deliberately makes it move.

Documentation as a query, not an artefact

The alternative CelinQ offers is not a better way to write the document once. It is a way of no longer needing the document to be a standalone artefact at all, by generating it directly from the current state of the model whenever it is needed, through the same Analyze Selected Package and Generate into Selected Package entry points used for diagram generation and model analysis. Instead of a solution architecture document being a file someone wrote eighteen months ago, it becomes something closer to a saved report definition — a scope, a structure, a set of sections — that can be re-run against the model's current state whenever a fresh copy is actually needed: before a governance review, at the start of an audit, when a new architect joins and needs an accurate starting point rather than a stale one.

This reframing matters more than it sounds like it should, because it removes the exact failure mode that makes hand-maintained documentation unreliable. A document that has to be manually kept in sync with a model will drift, because keeping it in sync is optional labour competing against every other demand on an architect's time, and optional labour that nobody notices being skipped is the first thing to get skipped under pressure. A document that is regenerated from the model each time it is needed cannot drift in the same way, because there is no separate copy sitting somewhere accumulating staleness between uses — the "document" is a view onto the model as it stands right now, not a snapshot frozen at whatever moment someone last found the time to update it.

What a generated document actually contains

A useful architecture document is not one long undifferentiated block of text; it is a set of recognisable sections, each answering a specific question a reader is likely to have, and generation follows the same structure a careful architect would use writing it by hand. A package summary describes what a package contains and why it is organised the way it is, grounded in the elements and structure actually present rather than a generic template filled in loosely. System descriptions cover the individual applications and components within scope, each drawing on its own notes, stereotype, and tagged values to produce a description specific to that system rather than an interchangeable paragraph that could describe any component in the portfolio.

An interface catalogue lists the interfaces a package exposes and consumes, which is exactly the kind of section that goes stale fastest under manual maintenance and benefits most from being regenerated on demand — a new interface added last week is present in a freshly generated catalogue with no extra effort, where it would simply be missing from a document nobody remembered to update. A dependency list does the equivalent job for relationships rather than interfaces specifically: what this package needs from elsewhere in the landscape and what elsewhere in the landscape needs from it, restated as readable prose rather than left as a diagram a reader has to trace by eye. A technology inventory summarises the platforms, frameworks and vendors recorded against the elements in scope, which is often the single section a governance or security review actually cares most about and the one most likely to be wrong in a document that has not been touched in a year.

Decisions, diagrams and revisions folded in

Beyond the structural sections, a generated document can draw on parts of the model that are easy to overlook when writing by hand under time pressure. Architecture decision summaries pull together the notes and tagged values that record why a particular structural choice was made, restating scattered decision records as a coherent narrative rather than leaving a reader to piece together the reasoning from fragments spread across several elements. Diagram descriptions accompany any diagrams included in scope with a written account of what the diagram shows, which matters for exactly the audience described in the companion piece on explaining models to non-architects — a diagram plus a plain-language account of what it depicts serves a wider range of readers than either one alone. Revision summaries, drawing on the workspace's ordered change history, can describe what has changed in a package's architecture since a chosen prior point — since the last review, since the start of a quarter, since a named milestone — turning the platform's own audit trail into a readable account of recent evolution rather than a raw list of revision identifiers a reader would have to interpret unaided.

The document that matters is the one someone actually reads before a decision gets made, not the one filed away after a project closes. Generation on demand means the document that gets read is never more than a few minutes old.

A worked scenario: the audit that used to take a week

Consider the specific moment this matters most: an external audit, or a public-sector oversight review, asking for a current architecture description of a specific system within a set deadline. Under the hand-maintained approach, this request typically triggers a small, unglamorous scramble. Someone locates the last solution architecture document, discovers it describes a version of the system that predates two subsequent releases, and spends several days manually reconciling what the document says against what the model — and, worse, sometimes what production actually looks like — currently shows, updating sections, chasing down colleagues to confirm details the document never captured, and hoping nothing important gets missed under the deadline pressure. The document that finally gets submitted is accurate as of the week it was hastily updated, and the whole exercise starts again from a stale baseline the next time an audit asks the same question.

Generated from the model on request, the same deadline looks different. The scope is set to the system in question, the sections needed — system description, interface catalogue, dependency list, technology inventory, relevant revision summary since the last audit — are selected, and a document reflecting the model's actual current state is assembled in the time it takes to review it rather than the time it takes to reconstruct it. The architect's remaining work is exactly the part that should require human judgement: checking the generated content against what they know, trimming sections that are more detailed than the audit needs, and adding the kind of contextual framing a generated document cannot supply on its own — not the mechanical work of chasing down what changed since the last time anyone looked. The week of reconciliation becomes an afternoon of review, and the difference is not a marginal efficiency gain; it is the difference between documentation that can support a real-time compliance obligation and documentation that can only ever describe a slightly outdated past.

Markdown, HTML and PDF: a direction, not a promise

Once a document's content has been assembled from the model, the natural next question is what format it should leave the tool in, and here it is worth being precise about what is a real pattern the platform is built toward and what is not yet a specific, shipped set of export options. The underlying architecture — a typed model and query API rather than an AI model wired directly into the sync engine — is designed with exactly this kind of downstream consumption in mind, so that a generated document's content can, as a matter of direction, be rendered into whatever format a specific audience needs: Markdown for a document destined to live in a wiki or a version-controlled repository alongside code, HTML for something meant to be read directly in a browser, PDF for the kind of formal deliverable a governance process or a client contract expects to receive as a fixed, signable artefact. Readers evaluating this or any similar capability from any vendor should ask specifically which export formats are available today, in what fidelity, and should not assume a capability exists simply because the underlying architecture makes it a sensible direction to build toward.

The AI pipeline behind the prose

Where an optional AI-assisted step is used to turn assembled model facts into readable, well-structured prose — as opposed to a purely templated rendering of the same facts — it follows the identical pipeline used across every AI feature in CelinQ: the architect's request, or a scheduled regeneration if a workspace has configured one, goes to CelinQ, which retrieves the model context in scope — the package, its elements, relationships, notes, decisions and revisions, filtered by whatever the workspace's AI policy permits — and an AI-assisted step proposes the document's prose from that retrieved context. That proposal is deterministically checked for consistency against the model before being presented, an architect reviews it before it goes anywhere the wider organisation will see, and only the reviewed, approved document actually gets used. Nothing in this pipeline writes back to the model — documentation generation is read-only with respect to the repository, in the same way explanation generation is — and the source of truth for every claim in the document remains the model itself, not the generated text, which means a discrepancy discovered later is resolved by checking the model, not by treating the document as an independent authority that might disagree with it.

Source-of-truth references throughout

A generated document that cannot be checked against its source is not meaningfully more trustworthy than a hand-written one that has quietly gone stale — it has simply moved the risk from staleness to unverifiable fluency. Each section of a generated document is meant to carry enough reference back to the specific elements, relationships and revisions it was drawn from that a reader with access to the model, or an architect preparing to sign off on the document before distribution, can verify any particular claim rather than having to trust the document as an opaque output. This is the same grounding discipline that runs through explanation generation, applied here at the scale of a full document rather than a single summary paragraph, and it is what makes a generated document something an architect can put their name behind rather than something they have to hope is accurate.

Scoping a document the way you scope a diagram

A generated document, like a generated diagram, is only as useful as the scope it is drawn from, and the same discipline of choosing a package, a viewpoint and a level of detail applies here just as it does to visual generation. A document scoped to a single component produces something an implementation team can use to onboard quickly; a document scoped to an entire domain, spanning dozens of packages, produces something closer to a portfolio-level briefing that a governance board would recognise, with correspondingly less depth on any individual system. Neither scope is more correct than the other — they answer different questions, for different readers, at different moments in an architecture's life — and the ability to regenerate the same underlying content at a different scope, without redoing any of the underlying analysis by hand, is one of the more practically useful properties of treating documentation as something assembled on demand rather than written once and filed away.

This scoping discipline also protects against the opposite failure mode from staleness: a generated document that tries to say everything the model knows about everything in scope, with no editorial narrowing at all, becomes as unreadable in its own way as a diagram with every relationship drawn on it. Choosing scope deliberately — this package, not the whole domain; these three sections, not all nine — is what keeps a generated document a genuinely useful artefact rather than a technically accurate but practically unreadable data dump, and it is a choice the generation step supports rather than one it makes unilaterally on an architect's behalf.

AI optional, generation still useful without it

As with every AI-assisted capability across the series, the prose-generation step described above is optional, off by default, and enabled explicitly per capability by an administrator through the Control Plane. A workspace that keeps AI disabled entirely, whether by choice or under sovereign mode, still benefits from documentation assembly that is templated rather than AI-authored — package summaries, interface catalogues, dependency lists and technology inventories built directly and deterministically from the model's structured facts, formatted into readable sections without an AI model rephrasing anything. The value of pulling documentation from the model rather than maintaining it separately does not depend on AI at all; AI, where enabled, improves the readability and narrative coherence of the prose on top of that foundation, and a regulated deployment can reasonably choose to keep that layer switched off while still retiring the practice of hand-maintained documents that quietly go stale.

The honest limits

Generated documentation inherits every limitation of the model it is drawn from, and a package with thin notes, undocumented decisions, and relationships recorded without explanation will produce a generated document that is accurate but sparse, because there is no reasoning step that can invent context the model was never given. This is worth naming plainly rather than glossed over: the quality ceiling on generated documentation is set by the quality of the underlying modelling discipline, not by the sophistication of the generation step, and a team hoping that generated documentation will compensate for years of undocumented modelling shortcuts will be disappointed by an honest, thin result rather than pleased by a fabricated, detailed one — which, uncomfortable as it is, is the correct behaviour rather than a shortcoming to fix.

There is also a real question of editorial judgement that generation does not resolve on its own: a document assembled from every fact the model records about a large package can be comprehensive to the point of being unreadable, and choosing what to include, what to summarise, and what to leave for a reader to find in the model directly if they need it is a genuine skill that an architect brings to reviewing and trimming a generated draft, not something the generation step is expected to get exactly right unattended on the first pass. And because the document's authority rests entirely on the model beneath it, a generated document is only as trustworthy as the synchronisation and governance discipline that keeps that model itself accurate — which is precisely the argument the rest of this series has been making about why the model's own consistency matters in the first place, and generated documentation is simply one more reason that consistency pays for itself.

Finally, a generated document is not a substitute for the kind of narrative context that only ever existed in someone's head — the political reason a particular vendor was chosen over a cheaper alternative, the informal understanding between two teams about who owns a shared interface, the history of a decision that was reversed once already and might be reversed again. None of that lives in tagged values or notes unless someone deliberately put it there, and no generation step can retrieve context that was never recorded anywhere the model can see. Generated documentation closes the gap between the model and the document describing it; it does not close the older, harder gap between what is written down anywhere at all and what a long-serving architect simply remembers. That second gap remains exactly as human a problem as it always was.