Always document flows

When you are adding something new to a large technical system, always document flows.

What is a flow?

By a “flow,” I mean a flow of information, events, user actions or business logic from point A to point B.

You start somewhere. You end somewhere. You might stop at a lot of places along the way.

Suppose you are implementing flows that cross lots of different systems or components.

Maybe each piece of the puzzle is straightforward, or even self-documenting. It’s great when you write a system component that’s easily understandable to future maintainers.

But if you have five or fifteen components, and they all have to talk to each other in a certain way, you need to understand the overall flow too.

If you don’t know what the flow is, it takes a lot of archaeology work to figure it out again.

That’s why you should document your flows — before you start to forget how they work.

Multi system flows

Here’s an imaginary flow that involves asking a document store for a document.

Behind the scenes, the document store is asking an auth service if this request is duly authenticated and authorized.

In turn, the auth service is asking a directory service for information about the requester. (Let’s suppose that in this imaginary system, our authorization policies are based on group memberships in a directory service.)

sequenceDiagram
    Requester->>Document Store: Requests a document
    Document Store->>Auth Service: Checks authentication
    Auth Service->>Directory Service: Retrieves the requester's group memberships
    Auth Service->>Document Store: Indicates if the request is valid
    Document Store->>Requester: Returns a document or else 401 Unauthorized

If I gave you the source code for all these services, even if it was the most readable source code in the world, it might take you some work to figure out the order of operations of this flow.

But if I gave you the source code plus this picture, you would instantly see what the overall story was, and it would be much easier to put the pieces together.

But I’m working on a system that has no flow diagrams

It sounds like I’m talking about some utopian world where people usually document things well.

In reality, we’re often working on existing systems that don’t have great documentation. They were built in a hurry or heavily modified since the initial design.

Now you have to add something new, or fix some bug, and you don’t know what the larger flow is.

What you should do is this: Go ahead and draw a flow diagram. Even if you are documenting something that has existed for years and has never been properly documented before. The best way to understand something that already exists is to write the docs that should exist for it.

By writing docs for existing things, I promise you will end up understanding them better than you thought you could.

(I’m not the first person to say this. I saw a team at work where every new engineer has to write docs for something as part of onboarding. I’m in awe of that.)

But what should my diagram look like?

I suspect this really isn’t too important, as long as there is something that captures the system in one view.

I personally am a very cartographic person and I like pictures, graphics, and technical diagrams. I love digital whiteboards like Excalidraw. The diagrams in this post are from Mermaid.

If it matters, I tend to prefer flow charts over sequence diagrams. Here’s a flow chart that covers the same things as the sequence diagram above:

flowchart TD
    Requester-->|Requests a document|DS
    DS(Document Store)
    AS(Auth Service)
    Dir(Directory Service)
    DS-->|Checks auth|AS
    AS-->|Checks requester groups|Dir
    DS-->|Returns doc or 401|Requester

But if you aren’t into the pictures, you can document a flow in words too, or with ascii art, or whatever. It would be OK to document a flow with a quick paragraph of “TLDR: Here’s how it all works.”

Here’s the sequence diagram without Mermaid:

Requester -> Document Store: Requests a document
Document Store -> Auth Service: Checks authentication
Auth Service -> Directory Service: Retrieves the requester's group memberships
Auth Service -> Document Store: Indicates if the request is valid
Document Store -> Requester: Returns a document or else 401 Unauthorized

Still pretty readable, right?

I really think it’s better not to bikeshed over documentation too much. That indirectly discourages people from doing documentation, in the long run, because often people aren’t in the mood for bikeshedding.

Don’t document the wrong things.

I’m not going to comment too much on technical documentation in general, but let me just say that it’s pointless to document things that are already obvious to a competent reader.

The codebase can be self documenting up to a point.

Let it do that. If your codebase is the source of truth for your input validations, your database schemas, your runtime configuration, or your class hierarchy, then let it express that naturally. Don’t write separate documentation for things that are sufficiently self-documenting.

Don’t add new flows when you don’t have to

Flows are often cognitively expensive.

This has a practical implication. If you have the choice between using an existing flow or adding a brand new one to a system, everything else being equal, you should prefer the former. Prefer fewer flows to more flows, given the choice.

This can significantly reduce cognitive load for future maintainers.

In conclusion

Document your flows.

Your future self, or your future colleagues, will appreciate it.