Just realized that documentation usually describes higher level of abstraction about code. It describers into what layers program is split, or what functionality several applications should provide. There must be a tool that would parse plain English statements with links to your code, transform it into some constraints, and then apply these constraints while developing. This will connect documentation and code more tightly, reduce chance of being obsolete. Say you're writing in documentation that: "The whole application is split into three layers: A, B, C. A and C layers never communicate. A consists of ComponentA1, ComponentA2. Components in C layers are all located in 'c_layer' directory". A tool gonna parse it and produce rules:

layer('A', 'ComponentA1').
layer('A', 'ComponentA2').

read_components_in_dir('C', "c_layer").

io_allowed(Component1, Component2) :-
  layer('A', Component1), layer('C', Component2), false;
io_allowed(Component1, Component2) :-
  layer('A', Component2), layer('C', Component1), false;
io_allowed(Component1, Component2).

I'm not sure I got the Prolog code right, but you get the idea. Thus it will throw a warning if it notices that code break constraint described in documentation. This will motivate programmers describe higher level assumptions about code in documentation, because it constraints it and provides some kind of safety. Just like static typing or assertion does.

Parsing natural language to produce accurate queries is a hard problem. But, you do not need natural language for that. For example, moosetechnology.org offers an extensive mechanism for writing queries like this. In fact, I believe this is the only way we can steer agile architecture.

Well, I still want to keep it as documentation first. Make it undestandable for humans first. I'm fine with manual assistance of translating plain text statement into formula.

The problem with this is that if you need to maintain it manually, it will get obsolete.

yeah

Top down design is useful. Bottom up should also be possible - e.g. write programs that grow organically over time but then you identify the boundaries, patterns extract the higher level descriptions. Doing this in form that remains connected and true to the lower levels is what could make this different from the alternative 'document the architecture in a google doc'.

I developed a method that does exactly that and used it in practice for the last 9 years. It works really well 🙂

The Synthesizer Generator A System for Constructing Language-Based Editors