> If they had to read their own document, it would probably be far better written.

Perhaps not; I've always had a strong impression, whenever reading documents derived from tax policy, that the "architecture" of such documents is the way it is mainly for maintainability.

Which is to say: the effective tax code at any given moment, is the emergent result of the interactions of all the current tax laws on the books. And there are many such laws. And those individual laws can be updated or repealed; and new laws can also come in that, through a few simple statements, make sweeping changes to the meanings of other laws.

As such, the tax-filing instructions, ideally, have to be constructed in such a way that they cope efficiently with someone being able to pull a single jenga-block out of the tower that is tax law, that topples over a whole slew of other instructions and definitions. The team of tax lawyers and technical writers that maintain the instructions should not have to sit down and rewrite every instruction on every schedule/form, just because one of the core definitions changes. Because that's gonna happen a lot! Every year, even!

If I was in charge of a team of (automation-minded) lawyers and technical writers maintaining the tax-filing instruction repository, I'd probably, ideally, want to factor out the instructions into separate modular files per law — with each file acting as a sort of Aspect-Oriented equivalent of Javadoc. (Or, actually, something very much like Inform 7. See e.g. https://i7-examples.github.io/Bronze/source_1.html)

So you'd see:

• Paragraphs that interpolate definitions as constants from other laws' modules;

• paragraphs that have implicit AOP hooks for other laws' modules to inject additional language into;

• the ability of a law to override specific sentences or wording of the language of the laws so far;

...and so forth.

This would be hell to read, but it'd sure make the job of dealing with changes in the law easy. (And it wouldn't be something you'd really read anyway — more often, it'd be something you'd carefully poke at, while watching the compiled result change live in a split pane. Like writing LaTeX in LyX.)

---

To be clear, I don't imagine that any existing set of tax-form language is actually maintained using some weird AOP DSL.

Rather, I imagine that the maintainers are manually doing the same business process that use of such an AOP DSL would formalize.

They're maintaining a very non-intuitive "storage architecture" for all the instructions that go into these forms, to minimize re-working when the law changes; and then — mostly manually, but maybe with a bit of Excel — collating them together into new schedules and forms each year.

And it's that "storage architecture" — despite not being something as rigid as source code — that still nevertheless forces the language of the instructions into the form you see at tax-filing time, with the weird grammatical shapes, the distant definitions, etc.

I have a simpler theory.

The law is the way it is because of the influence of lobbyists. Those lobbyists include lobbyists for companies that do things like payroll. They would like the system to be complex to provide a regulatory moat that keeps other businesses from competing with them. And by siding with this or that special interest that cares about their piece more than how sensible the whole is, the law is easy to turn into a mess.

Real life is imperative, dynamically scoped, all global variables, and every instruction contains an implicit branch.

I hadn't considered maintainability as something to consider in this area - appreciate the deep dive.

The saying bureaucracy can't help but beget bureaucracy is another thing that comes to mind.