Step 2. Architecture
Documentation Architecture
Most knowledge bases fail for the same reason: documentation architecture was never defined. Content grows without clear rules, articles end up in the wrong place, and the same information gets written multiple times in slightly different ways.
Documentation Architecture defines the structure your knowledge base is built on before content is written or rewritten. It’s the foundation that makes everything else easier: writing, maintenance, findability, and AI implementation.
Why architecture comes before everything else
Architecture is the set of decisions that determine how your knowledge base works as a system. Not the content itself, but the rules behind it. Every article’s role, home, and name. Decided once, applied every time.
When architecture is defined clearly, every article has a role, a home, and a name that makes sense. Writers stop making structural decisions from scratch. Readers find what they need faster. And as the product grows, the structure holds.
What happens if you skip it
Teams that skip architecture and go straight to writing or rewriting eventually end up in the same place. Content gets rewritten into the wrong structure. Duplication comes back. The same cleanup project appears on the roadmap every year.
It’s understandable. Rewriting feels like the obvious fix when documentation is bad. But what looks like a content problem is almost always a structural one.
Not sure whether you need architecture before rewriting? The diagnostic call will tell you.
Built for AI from the ground up
This is the phase where AI readiness is built in. A well-designed knowledge base gives AI tools something structured and reliable to work with. No more hallucinations.
What gets defined in this phase
Every engagement is scoped based on your product’s complexity and needs. For most teams, the architecture covers:
Modular documentation structure
A category structure designed around your product’s modularity, so content mirrors how the product works, supports reuse, and doesn’t require restructuring every time something changes.
Naming and placement rules
Consistent, predictable patterns for how articles are named and where they belong. Writers stop guessing. Readers find answers faster.
Metadata model
Where relevant: a metadata framework for customer-specific content, user roles, product versions, and other variables that affect what different readers should see.
Architecture support for AI use cases
Structure designed from the ground up to support AI-powered search, chatbots, and support tools, so your knowledge base is reliable for both human readers and the AI tools that pull from it.
Fixed article types
A defined set of article roles, each with a single, clear purpose. No overlap, no ambiguity, no articles that try to do too many things at once.
Content templates
Ready-to-use templates for each article type, so writing is faster, more consistent, and easier to maintain across contributors.
Versioning approach
Where needed: a clear approach for managing parallel documentation versions, so product updates don’t create documentation chaos.
What clients say
From the start, Anna took great care in understanding the technicalities of our developer ecosystem and product. Her holistically oriented approach and industry knowledge were instrumental in shaping our content.
Before and after: what actually changes
Before: Unstructured content
No clear agreement on where new content should go.
Same information exists in multiple places under different names, causing confusion.
Structure made sense at launch but becomes unwieldy as the product grows, slowing down updates and maintenance.
Writers must make structural decisions from scratch every time, leading to inconsistency and inefficiency.
Customer-specific content gets mixed with general content.
After: Structured clarity
Clear content hierarchy with agreed-upon categories.
Single source of truth with a unified naming convention, ensuring consistency and accuracy.
Scalable architecture that adapts to growth, allowing for easy updates and expansion without breaking existing structure.
Standardized templates and workflows, enabling writers to focus on content quality.
Segmented content with clear distinctions between general, product-specific, and customer-specific documentation.
Where this fits in the 3-phase process
Documentation Architecture typically follows the Documentation Audit. The audit identifies what’s broken, and the architecture defines what replaces it.
If you’re starting from scratch with no existing documentation, you can begin here directly. The architecture gives you the foundation to build on from day one, without accumulating structural debt.
After this phase, most teams move into the Documentation Rewriting phase, where they implement the new structure across existing content. That work can be done with me, with another consultant, or by your own team using the architecture as a guide.
Investment
Pricing is scoped per project based on the complexity of your product, the level of structural design required, and whether the engagement includes metadata modelling, versioning, or AI use case architecture.
Timeline: typically 4–6 weeks, longer for complex products or advanced AI configurations.
What I need from you: an understanding of your product, your users, and your current documentation situation — whether that comes from a completed audit or an initial diagnostic call.
This works in your existing tools. I design the structure to work in whatever platform you’re already using. You don’t need to migrate or adopt a new tool. Tools change. Structure should hold.
I’ll review your documentation and give you a clear scope and estimate before any commitment is made.
FAQ
Do I need a documentation audit before this?
Not always. If you already know your documentation structure is unclear, inconsistent, or difficult to scale, Documentation Architecture can be the right starting point. If you have a large or messy knowledge base and you are not yet sure what is broken, start with a Documentation Audit first. The audit shows what needs fixing, and the architecture defines what should replace it.
Can we do this without changing tools or migrating platforms?
Yes. This work is designed to fit your existing documentation environment. The structure, article types, naming rules, metadata, and versioning approach are built to work inside the tools you already use. You do not need a new platform to fix structural problems. If your current setup is workable, the right next step is to define the architecture before adding more content.
Is this only relevant if we want to use AI?
No. Documentation Architecture improves clarity, reuse, maintenance, and findability even without AI. But if AI-powered search, chat, or support tools are part of your plans, this is the phase where that foundation gets built properly. AI is only as reliable as the structure behind the content it pulls from. If AI is on your roadmap, this work should happen before large-scale rewriting.
Why should we fix the architecture now instead of later?
Because every release added to a weak structure makes the eventual rebuild bigger, slower, and more expensive. Structural problems do not stay contained. They spread through naming, placement, duplication, maintenance, and findability. Fixing the foundation early is cheaper than cleaning up after another year of drift.
A knowledge base without architecture is just content waiting to become a problem.
The earlier structure is defined, the less it costs to get right. Walk away knowing exactly what your documentation needs and where to start.