As an architect I’ve been asked to answer a lot of hard questions. I used to waste time figuring out how to structure my answers, preventing me from getting into a good flow sooner. Now I have a simple template that is easy to use, easy to read, and saves me that wasted time up front.

This template works for simple reports that are only a couple of pages, but can easily be adjusted or expanded for more complicated or much larger documents.

The template has these sections:

  • Purpose
  • Context
  • Recommendation
  • Paths Not Taken
  • Questions and Answers

I typically start a new problem by creating a new document and sticking in these headings. Next, I work to understand and document the context of the problem. Once that’s complete, I can design and describe my answer.

Surfacing Context

It can be tempting to jump straight into solutioning, however, and I cannot emphasize this point enough, you cannot design a good solution to a problem if you don’t understand the problem. I enjoy armchair architecture as much as anyone, but a good architect chooses the best solution for the circumstances, not just the first solution they thought of.

I always start with the first two sections of this document. This is usually only a page of text, but it really helps to frame and validate the problem from a business / customer perspective before starting the technical design.

Purpose Section

This first section has just a few brief sentences. It starts by explaining the purpose of the document, and then the scope of the document, and then a description of who it’s written for. It can seem a bit superfluous, but these details are important to remember when writing the rest of the document. It can also help a reader’s understanding if they know the context in which the document was written.

Example

This document recommends an approach to boiling the ocean. It is intended to be used during discussions with potential partners for the project. It is written for the CTO and the PMO.

Context Section

This is the most important section, and sometimes the hardest thing to get right. I only put in a few nuggets of information, but they need to be important. They serve as a sales pitch for upstream stakeholders and simultaneously guide and rationalize the decisions in the following sections. Even if the context seems obvious it is good to write it out.

I write some bullet points to articulate the importance of the problem and any significant constraints to the design. I keep it to just a few items, ideally between 3 and 6. If there are too many it becomes harder to process, if there are too few I probably shouldn’t be spending my time on the problem.

I like to polish each point a bit, but I also avoid flowery or superfluous language. Neutral defensible facts laid out clearly are a powerful tool for building alignment. It’s also good to write these in a way that makes sense to stakeholders who are not technically focused.

When I’m faced with an unclear problem, I will sometimes stick together some context statements based on my best guesses and send them out for feedback. Cunningham’s Law applies to all of design - it’s much easier to get corrections to a bad answer than ask for an answer in a vacuum. There are more specific techniques to help extract and validate this kind of information, but they take a lot more time from stakeholders so I try to use them only when necessary.

Example

  • Over 80% of internationally traded goods travel by sea. Marine freight is exposed to many dangers including navigational challenges, extreme weather, and piracy.
  • The sea level has been steadily rising due to human-caused climate change. As the ocean continues to rise, estimates anticipate hundreds of millions to billions of people will be displaced unless additional measures are taken.
  • The earth is simultaneously affected by an international housing shortage and the continual loss of essential farm land.
  • Eliminating the world’s oceans can simplify or make new solutions available to all of the problems above, which could in turn create numerous opportunities for raising and generating capital.

Document Title

A descriptive title is an important part of any document. I don’t want to spend too long figuring this out up front, but I do make sure I have a good one before any document gets circulated. Once it gets sent out, changing the name can break links and make it harder for people to find.

I also like to include the date in the file name and title. These documents are snapshots of the best information available at the time they are written. Since this is usually before a project has started, they lose a lot of their value once things get underway. A date in the title makes it clear when the document is an archeological artifact.

I always use the yyyy-mm format for dates because it’s precise enough, and the metric system is a good thing.

I could update the document as the project goes along, but I don’t see much value in this. The document has served its purpose once the decision is accepted and things start. If we need some sort of onboarding guide or architectural documentation, the parts of this document that are valuable for that effort can be easily copied and updated as needed.

Example

How to Boil the Ocean - 2023-08

Stakeholder Check-in

Once I have the above sections completed I like to check in with my upstream stakeholders.

Sometimes this process can take a bit of time. Depending on the size and urgency of the problem I might start on the technical design while collecting feedback. Parts of the design could be invalidated if the context changes, but usually any effort will still have nuggets that can be reused.

When I don’t get any significant feedback it can be a sign that the problem is either not well understood or not important to anyone. I might then schedule some workshops to dig in further before continuing.

Describing a Solution

There is a lot that goes into answering a technical question, and the way I go about it depends on a lot of factors.

Before I get too far into it, I like to think about how much I should be collaborating on the answer. Even if the answer seems obvious to me, it is sometimes valuable to involve the people who’ll be building the solution to ensure better buy-in once the project starts.

It’s also important to think about the acceptable amount of risk. If the cost of getting the solution wrong is huge, it may be necessary to do more thorough research or build and test some prototypes. If I’m just putting some rough estimates together to help plan the roadmap I will put in considerably less effort.

After all the thinking and validating work is done, I dump the best design into the document.

Recommendation Section

This is where I describe the answer to the question. I sometimes change the heading depending on the purpose of the document. If I’m preparing a thorough design for a complex system I might include multiple sub-headings and a few diagrams. For documents used more for resource planning I might just provide a brief architectural summary and a table of high-level tasks with t-shirt resolution estimates.

There are lots of ways to communicate designs. I do spend some time thinking about how best to do this. If I can use more efficient tools that are suitable for the audience and purpose of the document I can produce less. Smaller documents are easier to read, and easier to update when the feedback comes in.

Example

Use barges with nuclear fission reactors to boil the ocean water. As the sea level drops, the barges can be moved to ensure they stay submerged in water.

The steam generated by the reactors can also be used to generate electricity. Electricity not used for the operation of the project can be sold, adding an additional revenue stream.

Paths Not Taken Section

I’ve found it is often helpful to list some of the other possibilities that were considered but not chosen. Not everyone cares about this, but it can answer a lot of “what about X” questions from some personality types. It can also be helpful if you look back at a document years later. It’s not the most important part of the document though, so I try not to put too much effort into it. Bullet points and rough notes are usually enough.

Example

  • Use a giant laser from space.
    • The laser beams would be a hazard to air and space traffic.
  • Accelerate global warming by burning a lot of oil.
    • The required oil would make this approach significantly more expensive than other options.
    • This option could generate too much negative PR.
  • Pump the water into on-land boiling stations.
    • Cost of pumping would be significant.
    • Hoses and pumping stations would need to be continually added as the sea level drops.
  • Use nuclear fusion reactors to generate heat.
    • The technology is not mature enough at the time of this writing. If it does become feasible during the project we could update the design for any new barges being constructed.

Questions and Answers Section

There will often be some things that I want to communicate that don’t fit anywhere else in the document. A Question and Answers section is really versatile, and it’s an easy place to add more information when responding to feedback.

Example

  • Is boiling the ocean really a responsible thing to do?
    • That is outside the scope of this document.
  • How will the boiling stations deal with salt accumulation?
    • This will need to be investigated further if we proceed with this project.

Customization

Just like in software development, I find it best to use the simplest document that can possibly do the job. The less I write, the easier the document is to read, and the more time I have to work on my next project.

If I don’t need one of the sections above I’ll remove it. I can also add new sections as I need them. I have added sections with estimate tables, rudimentary project plans, optional features, glossary of terminology, and so on.

Template

I’ve created a standalone page with the example from this post so you can use it as a template for your own work. You can find it under Resources, Architectural Report Template. If you do use it I suggest replacing the contents before sharing it to prevent any embarrassment.

Acknowledgements

This template was inspired by the Decision record template by Michael Nygard which I also recommend for its intended purpose.

If you want to know more about how to write architectural reports, gather information, or validate designs, I highly recommend the book Design It!: From Programmer to Software Architect by Michael Keeling. I learned a lot from this book, and have referred to its contents many times since.