Writing

Architects must write. I used a variety of tools to write like Evernote, Grammarly, Google docs, Markdown files, MS Word, and many others. Today, the best tool for me is Markdown files.

Markdown files are simple and lightweight, they work with any AI Grammar tool. They are also universal and portable. In my humble opinion, I do not have the perfect writing tool yet. I might need to build my own one day, but I think less is more. You need to focus on your ideas, so fewer distractions is the key.

Architects need to write:

• Principles
• Guidelines
• Trade-offs
• Decisions

When you write something down, you are dumping your brain and therefore doing the same as an engineer when they fire up a PR. You are allowing others to review. Written documents scale, because many people can read them, and they might last forever.

Why you need to know this?

This probably is the most non-obvious thing. Back to the code review, you can only review because someone wrote code. How do you review architecture? Well in part it can be with diagrams, but you can’t do 100% of all the things with diagrams. Because architecture also drives:

• Technical Strategy
• Decisions
• Guidance to engineers
• Standards and practices

Even on Architecture and design you can only best capture by writing. When you write, again we have something to review, to socialize. Architects must write, otherwise how do they review what they do? How do they convey their ideas? How do they socialize their vision? Writing also has a nice property which - enables scaling - because many people can read your writing, and you can reach a larger audience.