I like to Ha Ha Only Serious that the ask for documents is just a standard technique for getting out of having to care about whatever it is you're talking about. If they ask you for documentation, and you don't have it, you automatically lose and they get to ignore you.

If you always have it, eventually they stop asking you. (Until someone new joins and tries it on you.)

Cynicism aside, it's useful stuff anyhow. Rubber ducking is a well-known debugging technique where you describe your problem to someone who doesn't have your context, even if it's only a rubber duck, and the mere act of describing will often reveal the problem. Writing documentation for other people is the closest equivalent for rubber ducking at the architectural level. When you're sitting there writing the complicated things you have to do to do X, you get an outsider's view of the situation. Take that and use it as motivation to fix the problem. Try very hard not to be just cynical about it and let your sensitivity to that signal become calloused... it is incredibly useful!

>But mostly I just needed to get used to the act of sitting down, drafting, and writing a design document. I also needed to encourage the team to have a bit of discipline and design before coding.

In the architect role, I write a lot of documents as well, but mostly for the purposes of: 1) Organizing my own thoughts 2) Summarizing for the benefits of upper management 3) Influencing discussions with peers 4) To serve as a record that someone interested can refer to

The documents are generally higher-level and tailored to the audience that I intend to read it. In very rare (none?) cases am I ever getting detailed enough to get to this is exactly how we're doing it, since what I'm really trying to do is to set the overall direction and goals in pursuit of strategic objectives. I let the experts in individual domains handle the details. The entire process is also iterative. I build consensus through synchronous, high-level discussions ("wouldn't it be great if") and, through those, get a handle on the challenges faced by various orgs. I then try to coalesce that into something that benefits each org in some way, while still serving the overall objectives (developer velocity, flexible infra, performance, etc). My goal is to influence & inspire rather than dictate and own.

Worse, hardly anyone ever updates them.

But you still need to write, not necessary a speciation or tech document but all kind of notes and summaries for yourself. So that the you in two month can go back to a decision dinner two month before and reevaluate it with your new knowledge.

Also depending on the company they might give you the task of writing a less technical describing if the system for e.g. investors.

Lastly in my (little) experience asynchronous communication interleaved with small amounts of synchronous information discussions is king when it comes to the doing complex technical decisions (like which database or architecture to use for the next project).

But then I don't have too much experience in this area so take it with a grain of salt.

I'm on the ops-architect end and I read design docs and usually steal all of the plantuml and everything else I can find as nobody ever (aside from the developer of the feature) can help me track down or troubleshoot problems and I find most developers to be very disorganized (I was too until recently and it's still something I work on daily). So the documentation is appreciated. I also write a lot of ops-focused docs and tools, like stuff to lower MTTR and just generally help my ops teams relax and be lost less often when alerts come in. An ops person should never get an alert at 2am and be completely lost, no playbooks or guidance or anything because a lack of implementation documentation, I've been there, it sucks and will make you regret your employment.

I don't think most of that gets read either. But I still do it. I just assume most people are siloed in their own projects and barely have time to get those done so reading ancillary stuff is on the backburner. But if some emergency ever comes up at least it's there and if I'm on a mountain I got everything out of my head so you won't need me to walk you through how something works over the phone.

With that said, I face immense frustration when I go into a microservice repo that is scaffolded hoping that some golang developer updated the readme to actually be relevant and not the scaffold template and 99% of the time for internal stuff it's never, ever touched. Please do some documentation for Ops/new-devs, etc. That extra 30-2 hours of work will save half a day of some new person trying to launch your service in KIND or whatever, now compound that over every new person/outage/time you've had to explain something that you didn't document. The readme.MDs in every single one of your microservices should not be a base template with zero touching. It's not hard work to give someone who has never touched it some breadcrumbs on what your service does.

Half the time I go in there when something is already broken and the stress is high hoping for simple stuff to get me going, even just some basic UML of what apis its talking to, what kubernetes resources it needs, what RBAC permissions, etc. Think of yourself having never touched the service and leave some pointers/best-practices for someone who has never touched it or troubleshot it (like your ops people when you throw it over the fence for deployment).

Having to figure out your microservice architecture via container logs when SHTTF is miserable.

I've heard it said that a plan is rarely followed but the act of planning is invaluable. I wonder if writing documentation would fit similarly.

People should accept the fact that people are busy and often don't have/take time to read documents offline.

I really like how Amazon mitigates that, you hold a doc review meeting. Everyone gets together, reads the document (in silence for ~30 min, or however long it takes), and then discusses. Then you know everyone has the proper context and knowledge for a good discussion.

This depends enormously on the culture of your organization. And in a high-level role like this you're in a strong position to shape that culture.

I frequently write architectural documents and as a team we find it a very useful way to collaborate. We structure them as RFCs (meant literally, in that the document is designed to solicit comments, and so are often proposals). I've never had an engagement problem with them.

I, on the other hand, try to write technical document to not have to answer the same questions twice. When some one ask me anything that I have a doc cover it, I give them the link. If I don't, I answer, then check and update my doc. That works well for me so far.

On the other hand, everyone reviews the figures in detail. Therefore I’ve always used the text as a way to document the decisions behind the figure, mostly for myself, and to clarify any ambiguity in the figure itself.

Write an overview in narrative, and the rest in headings and bullet points.

Keep the substance to 1-2 A4 pages. Nobody sane wants to parse more than a tiny bit of narration.

Try to use Wiki, Google Docs, or shared docs in Office 365 if at all possible. Email chains are a collaboration fail, and Word docs are where information goes to die.

As someone currently migrating a rusty old Oracle enterprise system, please write documents. Migrations always blow up in complexity because someone didn't realise that there were 20 feeds from X DB and that a decade of hacking lived under the skin of their simple workflow system.

Same. I Always talk and discuss with diagrams, the more colourful the better (like AWS components).