In an age of Genies magically whipping up thousands of lines of code based off of some context, your Engineering documentation matters more than ever.

Is is more and more easy to do many things, to pump them out. But how do we know we are doing the right thing?

The Document

The Context

Before any solution can be introduced, it’s problem must be introduced. But for a problem to make sense, we must have a shared understanding of the context surrounding the problem.

Who is using this thing? Why is it the way it is? What do we mean by these core domain terms that we keep using?
It may seem silly, but going back to basics and grounding any Engineering Document in the context is a key step. Both for Humans and for Agents to have any chance of having a shared understanding of what is going on.

This section will set the stage from your audience, about how we understand the problem, and the problem the stage for how we understand the solution.

If you recieve a lot of comments on your doc about the context, disagreement about where we currently are, there is no way we can have a successful conversation about where to go to next!

One does not have to go from scratch every time here. There may be some core docs you can link out to in your context that explain the current situation. But do not skip this step.

The Problem

This is the crux of the document. Possibly even more so than the solution.
If you are not solving a good problem, it doesn’t matter how good your solution is.

We need to understand our problem in depth, and the potential impact that solving the problem could have. In an age where producing the solutions is getting cheaper and cheaper, the problem selection step becomes more and more important.

This is where the leverage is. Do we understand the problem? What will our users gain if we solve this problem?

Get a Temperature Check

Before we go about coming up with a solution, checking in with a couple of trusted colleagues about whether they agree this problem is worth solving or not is a good idea.
It can solve us a lot of wasted time, and it also might surface collaboration oppourtunities where people are already working on something in the same area on a variation of the problem or a related problem.

The Solution

It is important to present a strong single recomendation, but also to present tradeoffs that have been analysed, and other options ruled out.

Having a single recomendation is better than making your audience do the work of arguing over the tradeoffs,
and including the other options that were ruled out is important to ward off all of the questions you will inevitably be asked.

I have found that if you do not include other options considered, when you present your documentation you will wind up getting asked about other options anyway.
For example if we want to spin up a new service, you will be asked why it can’t just be a part of the existing service. So it is much more effective to simply include this option, and the tradeoffs, and why you went the way you did in your document to begin with.

The Lifecycle of an Engineering Document

Your document will have a lifecycle, explicit or not. I find it best to make it explicit in the header of the document which stage of this lifecycle it is in.

Draft

Even while your document is in draft, I prefer to publish it, just with a big [DRAFT] at the top.
It makes it easy to elicit early feedback from ones you trust.

Before removing this from draft, I have found it valuable to ask an LLM to review my document with something like

You are a Head of Engineering for . Review this document and give me feedback. Analyse the problem, whether it is worth solving at all, if we have enough data, point out any fuzzy areas that need clarification, and critique the proposed solution.

I find that this shortcuts that first round of reviews where you have accidentally written things like “a lot of customers”, where your HoE will inevitably ask you “How many?” or “really slow” and you will be asked “how slow?”

AI can be very useful at shortcutting this first round of mechanical feedback, and let the humans focus on the real problems.

Ready for Comments

This state shows that your document is ready for others to try to tear it to shreads.
It indicates that you are inviting open and honest feedback and challenge to your ideas, and that you have gotten it to a reasonably stable place.

You are usually looking more for comments around the solution here, as the problem has hopefully been fleshed out already.

Accepted

Congratulations, you have probably convinced a room full of smart and opinionated people that what you want to do is worth doing! Record this outcome in your document by updating the status, and maybe linking out to meeting minutes.

Implementation

A document is only as good as it’s implementation. If we just write things and don’t do things, that doesn’t generate any business value.

Depending on the size of the doc, this step might look very different. You might need to secure funding, in which case the managers will be very interested in those first two sections! Probably more so than the solution!

Obsolete

Even once a document is completed and the solution is implemented, some day it will be replaced.

Software is not done until it is decomissioned and teared down. Even a solution which is perfect now, might not solve tomorrows problem.
We need to remain free of ego, and be willing to move away from the solution we came up with.

Do not fear the Obsolete stage. It just means that our work has done its job and taken us to the next level.