Introduction

Metz is a powerful tool for creating interactive diagrams with TypeScript code. It lets you express complex systems visually and interactively.
But it’s also a long way from drawing boxes and lines. It’s a different way of thinking about documentation and communication.

​

Mental Model

With diagramming tools, we are well aware that we are dumbing down complex ideas because there’s not much we can do with the primitives these tools provide.

It’s like Brainfuck, too simple to do anything complex.

Metz lets you think of systems in terms of code. You don’t need to worry about how and where to place a box, you need think how your design should work.

​

Why code?

It’s familiar, we as engineers feel comfortable with it. But if we were to use a DSL which lets us create boxes and lines, then it’s the same problem, presented differently.

We want to use code, not for the sake of it, but because of the freedom it provides us to express complexity.

​

What kind of code?

When we are building software, we write code with the intention that it does what it’s supposed to. No strings attached, no frills.

It’s the exact same with metz.

Say you are building a system which has a polling mechanism and it fetches data from one database and updates another. You shouldn’t have to write code to create a box for a poller. You should be writing code FOR a poller.

So you might come up with a design that can say:

And the code can look something like this:

class Poller {
    private ordersTable = new OrdersTable();
    private pollingCollection = new PollingCollection();

    poll() {
        // Step 1
        const updatedOrder = this.ordersTable.updateOne(
            {
                status: 'processing'
            },
            order => order.status === 'pending'
        );

        // Step 2
        if(!updatedOrder) {
            return;
        }

        this.pollingCollection.insert({
            id: `poll_${updatedOrder.id}`,
            order_id: updatedOrder.id
        });
    }

}

No way this code can be used in production, but that’s the thing. It’s not for production.
It’s simply a way to express our design using code, that’s it.

In return, this is what you get from metz:

We take your code, which says nothing about how to present it, only talks about behaviour pertaining to your design. Then we run & render that behaviour.

​

Advantages

​

Minimal overhead

You don’t have to burden yourself with translating or dumbing down ideas.
Just write code!

​

Complexity is easy to express and easier to understand

It’s subtle, but notice that there are two pollers but not two entries in polling collection.

The proposed design of a system like this, would have this crucial fact lost in a footnote. And when implementing the design, someone could easily miss this required behaviour.

But when you use code, you weild the perfect medium to express such critical facts. And pair that with metz, this behaviour becomes not only apparent but a first class citizen of documentation.

But enough words, let’s get down to details in the next section!
We will learn how to write code in metz, its building blocks and its rules.