Codifying Architecture: Diagrams as Code

Sun, 03 Mar 2024 00:00:00 +0000

(Originally drafted in August 2019 during my tenure at Xero. Republished here in March 2024 with updated context and removed proprietary references)

Engineers love writing code. There’s nothing quite like instantly seeing the fruits of your labour appear on a screen – immediate feedback and the joy of getting something working.

Engineers, however, tend to hate writing documentation. It takes time, it’s seen as overhead to “real work,” and so it falls by the wayside. The next engineer to come along is told: “Oh, that’s out of date – just look at the ‘self-documenting’ code instead.”

Plantuml on Maceage's Blog

Codifying Architecture: Diagrams as Code