The problem
Picture an operation with dozens of e-commerce projects running in parallel, multiple squads, and all the technical knowledge living in the heads of half a dozen people.
Someone knew how to fix that specific VTEX IO checkout bug. Someone else had figured out a workaround for a FastStore limitation. A third person had built a component everyone needed but nobody knew existed. And the moment any of those people went on vacation, got sick, or quit, the knowledge went with them.
Every new project started from scratch. The same mistakes repeated. The same problems got solved all over again, by different people, in different ways. Onboarding a new dev took weeks because there was no single place to look and understand how things worked. The answer to almost everything was “go ask so-and-so.”
I watched this happen every day and thought: this doesn’t scale. An operation this size can’t depend on people’s memory.
What I was seeing (and nobody was naming)
One of my many obsessions is Systems Thinking. And what I saw at Cadastra was a classic information-flow problem - not a people problem.
Donella Meadows talks about leverage points: places where an intervention shifts the behavior of the entire system. One of the most powerful is information flow. The problem isn’t that the knowledge doesn’t exist - it does, it’s being generated every day by every dev who solves a problem. The problem is that it has no path to get where it needs to go. The person who found the workaround knows about it. The person on the next project doesn’t. The information exists in the system but it’s trapped - no channel, no flow, no structure to carry it.
If you look at organizational knowledge as a stock (in the dynamic-systems sense), it has inflows and outflows. The inflows are everything the operation learns day to day. The outflows are turnover, technology change, memory that degrades over time. In most operations, the outflows are automatic and constant - people leave, technology shifts, folks forget. But the inflows into the documented stock depend on deliberate effort. The result is predictable: the stock drains over time. The organization pays to relearn what it already knew.
The knowledge silos everyone complains about aren’t a communication failure - they’re a consequence of the structure. If there’s no path for the VTEX IO team’s knowledge to reach the FastStore team, the silo isn’t a bug: it’s the system working exactly as it was (not) designed.
The decision
Nobody asked me to do this. It wasn’t a task, there was no Jira ticket, there was no deadline. I just started building.
The first version was a folder with a few markdown files. Then it became an Astro Starlight with a deliberate structure, hosted internally for the company. Then it gained automation scripts, a sync pipeline with the projects, Jira integration, documentation templates, and became the technical reference for many people across the operation.
Architecture as intervention
The structure I designed isn’t a folder organization - it’s a decision about how knowledge flows. Each directory is a channel:
cadastra-docs/
├── solutions/ # Soluções reutilizáveis (componentes, hooks, integrações)
├── platform/ # Guias por plataforma (VTEX IO, FastStore)
├── projects/ # Implementações documentadas por cliente
├── process/ # Fases, checklists, workflows, experimentos AI
├── troubleshooting/ # Erros conhecidos e soluções
├── templates/ # Templates de documentação
└── scripts/ # Automação (MD→DOCX, sync pipeline, Jira)The organization is by type of knowledge, not by team. That’s intentional. If it were by team (squad-vtex/, squad-faststore/), it would be replicating the silos inside the documentation. Organizing by solutions/ and platform/ creates cross-cutting paths - any dev from any squad finds what they need without having to know who made it.
Every documented solution has a source field that links straight to the source code. Every project has its architecture, dependencies, and decisions recorded. Distinct checklists for B2B and B2C, for FastStore and VTEX IO. And the automatic sync pipeline that pulls documentation straight from the repositories exists for a specific reason: to reduce the friction of entry. If documenting requires opening another system, logging in somewhere else, remembering to do it - it doesn’t happen. If the documentation is pulled automatically from the repository where the dev already works, the barrier drops.
Nonaka and Takeuchi describe four movements of knowledge: it’s born tacit (in someone’s head), gets externalized (written down), combined (connected to other documents), and internalized (when another dev reads it, applies it, and develops their own understanding). Most knowledge bases only support externalization - “just write it down.” cadastra-docs was designed to support all four: templates that make externalization easier, the directory structure and the source links that handle combination, the practical and actionable format that eases internalization, and the very existence of a shared context that improves socialization between devs.
What changed
Before cadastra-docs, the answer to “how does X work?” was “go ask so-and-so.” Now it’s “check the docs.”
New projects start from ready-made templates and checklists. Solutions that used to be reinvented every week are now found, reused, and evolved. Onboarding that took weeks now takes days. And when someone solves a new problem, the solution doesn’t die with that person - it goes into the docs.
What I didn’t foresee was the compounding effect. The more people use it and find value, the more people contribute back. The more people contribute, the more useful the base becomes. It’s a reinforcing loop - and once it starts spinning in the positive direction, it’s hard to stop. The opposite is also true: knowledge bases that are born badly structured fall into the inverse loop (nobody finds anything → nobody trusts it → nobody contributes → the base rots). The difference between those two fates is structural, not motivational.
The base became so central that it served as the foundation for the AIvengers Initiative - the experiment’s 28 technical documents were born there. Without the documentation infrastructure, that experiment simply wouldn’t have happened. That’s maybe the best example of what it means to build knowledge infrastructure: it enables things that wouldn’t exist without it - things you can’t even imagine at the moment you’re building it.
Technologies
- Astro Starlight - auto-generated documentation site
- Node.js - automation scripts (MD→HTML, MD→DOCX with Cadastra branding, sync)
- Pandoc - document conversion for Google Docs
- Jira API - integration with dashboards and reports
- Claude AI + MCP - context engineering for assisted development
What I learned
The hardest part of creating a knowledge base isn’t technical - it’s cultural. Convincing people to document, to trust that the time invested in writing is worth more than the time saved later. In the beginning it was just me writing. Little by little, when the devs started finding answers that used to require interrupting someone, adoption came naturally. The reinforcing loop began to spin.
The most common mistake I see in documentation initiatives is treating knowledge as a static artifact - a document you write, file away, and you’re done. Knowledge is a flow. It needs maintenance, channels, structure that sustains the movement. If you build a repository, you have a shelf. If you build a system with flows, feedback, and self-reinforcement, you have an infrastructure for organizational learning.
What I did with cadastra-docs wasn’t “documenting projects.” It was an intervention in the structure of how the operation generates, retains, and applies what it knows. I changed the channels through which information moves, the rules for how it gets captured, and the conditions for the system to feed itself. The documentation itself is just the visible artifact. The real change is structural.