Your OutSystems Estate Is Not Self-Documenting

Ask most OutSystems teams where the documentation is and you get the same answer. It is in the platform. Open Service Studio, the flows are right there.

It is a fair answer, and for a young estate it is nearly true. For an estate that has run a business for five or more years, it stops being true, and most teams find out at a bad moment.

Why it feels documented

OutSystems is visual. An action is a flow you can read. A screen shows its own bindings. Service Center lists every module, Discovery draws what depends on what, and tools like OutDoc will generate hundreds of pages from the factory in an afternoon.

So the estate looks like it describes itself. Compared with a legacy codebase, it does. Nobody has to dig through source files to learn that a module exists.

The trouble is what all of that describes. It describes how the system is built. The question people bring to it is a different one: what does the system do, and what is it supposed to do?

Three things the model cannot tell you

What the business calls things. The entity is named one thing, the screen label says another, and the operators use a third word that appears nowhere in the factory. After a few years and a couple of renames, the mapping lives in people’s heads. A new developer reading the model learns the stored names and none of the real ones.

Why a rule exists. The flow shows that a record with a certain status is skipped. It does not show that this was added in 2022 for one customer after a billing dispute, and that the customer has since left. The model keeps every decision and none of the reasons.

What is still alive. Mature estates carry entities from features that were dropped, actions that only run at year end, and branches that have not been reached in years. In the model these look exactly like the parts that run every day. Reference counts tell you what is connected. They do not tell you what is used.

None of this is a flaw in the platform. A model is a description of structure, and these are questions about meaning.

Where the gap shows up

For long stretches it does not show up at all. The team that built the estate is still there, and they are the documentation. Then one of four things happens.

Someone asks for an estimate. Every estimate on an undocumented estate carries a hidden line for finding out what the thing does. When that line is missing, the estimate is wrong by the size of it. We wrote about the first read in Reading a factory before you quote it.

The team changes. The architect who knew why the skip was added moves on. Handover covers the modules and the deployment steps, because those can be shown. The rules do not get handed over, because nobody ever wrote them as rules. More on that in What makes an OutSystems platform hard to hand over.

The ODC conversation starts. Converting an estate means deciding where each producer module lands, and that decision depends on what the module is for. The producer module inventory gives you the questions. Half the answers are business knowledge.

Someone wants to change a core rule. The change is small. Finding every place the old rule was assumed takes three weeks, and nobody is sure the list is complete.

In each case the team ends up reading the factory under time pressure to answer one narrow question, and the answer is thrown away afterwards. The same reading gets done again the next time.

What a useful document looks like

The usual reaction is to document everything, which produces a large folder nobody reads and nobody keeps current. The opposite reaction is to generate documentation from the factory, which produces the model again in a different format.

A useful document is smaller than the first and different in kind from the second. It has four parts.

The path. How a piece of work moves through the system from start to finish, in five or six steps, in the operators’ words.

The rules. Each one in a sentence or two of business language, with no action or entity names. “A charge with an end date inside the period is billed up to that date.” If a rule cannot be written this way, it is not understood yet.

The name map. What the operator sees next to what is stored. Short, dull, and the page people open most.

The contracts. Every file, message or integration that leaves the system: columns, formats, order, and what the receiving side assumes.

One thing makes it trustworthy: it says what it does not know. Open questions are listed in plain sight, with who they were put to. A document that admits its gaps can be relied on for the rest.

Start with one path

You do not need the whole estate written down. You need the path where a mistake costs money.

In most operational systems that is the one that ends in a file to finance: set up, calculate, review, approve, export. It is usually a small share of the modules and most of the risk. Written properly, it is a few weeks of work for someone who can read a factory, with the heaviest call on the business in the first month.

The rest of the estate can follow in order of how much it feeds that path. Much of it never needs more than a paragraph.

To see where you stand today, there is a five-question test in a field note: Is your estate written down?

When to do it

The best time is when nothing is on fire. A quiet quarter, a programme on hold, the months before a planning cycle. The people who know the rules still have time to answer questions, and nobody is waiting on the result to unblock a release.

The usual time is the worst one: in the middle of a conversion, a handover or an incident, with the answer needed by Friday.

The estate will keep working whether or not this document exists. What changes is how fast you can decide things about it. An estimate takes days where it used to take weeks. A new architect is useful in their first month. An ODC plan starts from what the modules are for, with the scan as one input among several.

That is what the document buys: an estate that is cheaper to change, starting with the part that matters most.