[squeed]

You have to learn to write, and get comfortable doing it.

When I was the (de-facto and later de-jure) architect, I was too reliant on in-person synchronous discussions. I neglected my e-mail and design-document skills.

The result: everything had to be synchronous. Chat was a wasteland. Decisions where one just had to Sit Down and Think wasted multiple people's time. I realized I was subconsciously avoiding writing long documents.

Part of the problem was - no kidding - I needed a new glasses prescription. 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.

Later, as I transitioned out of a "move-fast-and-break-things" place to a large open-source project, my learned avoidance of writing definitely hurt me. I was not practiced at asynchronous design and development.

[tootie]

I've been an architect for a long time and have written a lot of tech documents and can say with confidence that no one ever reads them.

[jerf]

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!

[fatnoah]

>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.

[dathinab]

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.

[mjayhn]

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.

[michaelbrave]

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.

[tj-teej]

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.

[jasonlhy]

I think document is good for filling the details, but it will not solve all the problem . And I kind of hate Architect with an extreme authority from top to the bottom and just assume people know everything. From my experience, casual communication between developers is an important factor in software development.

The perfect role of architect I believe is an individual contributor. People just come to ask your idea and respect you to make the majority of design. And you need to help other to understand your idea.

[jefftk]

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.

[tootie]

I honestly don't think it's even valuable to write them. It's a manifestation of BDUF. The more detail you put into a document up front, the more wrong assumptions you're committee to paper. It's basically a guess. Same reason we've adopted agile as a mindset, architecture needs to be agile too. Documenting a system as it's built is much more useful.

For context, I mostly work in consulting. So I don't have a lot of authority to impact culture as much as I try. Doing handoffs is a big part of my job and even if I hand off a detailed explanation of everything we've done, I'm still guaranteed to get asked about everything I've already written down.

[edraferi]

I'd much rather have a clear record of the assumptions made & rational for them than have to discover them later when problems crop up.

[tootie]

Agree this is probably the most beneficial application. You can reference it almost like a contract.

[rabidrat]

How do you get people to read things? I've also written plenty into the void, and have no idea how to get people to actually read things (without being a jerk about it, which is not the culture I want to shape).

[stronglikedan]

While I don't make people read things, but if the answer is in something that they should have already read, I do use their questions as a teachable moment. Instead of just giving them the answer, I tell them where to find it. Usually with a friendly note indicating that the docs are usually the quickest way to get an answer.

The old teach-a-man-to-fish adage, if you will. Some people never learn, but I'm still not unfriendly towards them. Although, I do start to silently de-prioritize their questions over time. Most people do learn though, and they're the ones that start asking for clarifications instead of complete answers.

[jefftk]

Things I've found useful:

* Use a platform where it's very easy for people to give feedback. I've used Google Docs and Quip.

* Write documents when there's real disagreement about how something should work.

* Ask specific people for feedback on your documents.

* Ask other people to write things, read what they write, and leave good comments.

* Have a regularly scheduled meeting for reviewing team documents to get feedback. Anyone can sign up with a doc they want reviewed.

[edraferi]

Also:

* Write clearly & concisely

* Use good headers and provide a table of contents

Here are some useful resources for writing better:

https://www.plainlanguage.gov/

http://www.hemingwayapp.com/

[gtf21]

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.

[letientai299]

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.

[qznc]

Me too.

I have colleagues who do the opposite. They often complain that they don't have the time to write documentation because they have to explain stuff to people all the time. Thus, I believe writing saves time eventually.

[esmi]

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.

[twhitmore]

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.

[ilikerashers]

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.

[yonixw]

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

[cbanek]

Agree. Usually when I write a document, it's usually centered around a few "hero" diagrams, with most of the text explaining it. Afterward it's always the pictures that are the most useful for me, but maybe we're just visual learners!

[manojlds]

Did you properly read the parent comment you are replying to?

[rammy1234]

It's ok if he didn't, comment was positive way to say what he does instead of saying that was crap.

[gregmac]

> avoiding writing long documents.

Just to pick on this bit: You should still avoid writing "long documents". Spend the time to make your documentation as concise as possible. And make no mistake, making it shorter is much more effort and takes longer:

    "I would have written a shorter letter, but I 
    did not have the time." -Blaise Pascal, 1656

Nobody reads big, long wall-of-text documents. Break things into smaller sections, and be sure each section has a clear audience in mind (developer implementing initially? support debugging a production problem? QA building test cases? tech writer making user-facing docs? PM?).

Good rule to retroactively build up your docs: When someone asks a question, answer it with a link to the docs. Sometimes this means writing new documentation.

[mcv]

I fear this is great advice. I too avoid writing documents. Or even reading them. I want to have my hands in the code, but it's increasingly clear to me that I need to write more stuff down.

[gonzo41]

I don't fear writing documents, but i do work with a lot of people who do fear reading! I've found a really good trick is to highlight key figures or a few standout grabs in the early paragraphs of the text and then to have more substantial higlights towards the meaty parts of the document.

Essentially it's like having the bullet points and full document in one. It;s resulted in a lot of people getting interested up top and being tricked into reading down the bottom.

Give it a try sometime.

[squeed]

For sure. Part of being a successful writer is communicating in a way that is most effective for your audience.

Rarely is a wall-of-text the right answer. Bullet points, flow diagrams, and examples are all helpful techniques when writing for engineers.

[xinau]

I had/have the same problem, what helped me a lot was to write down what I've learned (roughly bi-weekly). Another booster was to stick to the same document structure for example NABC for proposals and ideas.

NABC: https://nielschrist.wordpress.com/2012/07/13/the-nabc-method...

[larrywright]

Writing would be valuable to me even if nobody else ever read the documents. I find that writing helps me think through a problem much better, and in the end I have a better solution.

[logfromblammo]

Learning how to make concise, effective infographics is a part of learning technical writing.

A picture may not always be worth exactly 1000 words, but images with high cognitive density are usually worth putting into your document.

[jugg1es]

I can't stress how important it is to get good at writing design documents and producing effective diagrams. If you do not produce these artifacts, it is very difficult for your developers to do what you want them to do. You end up spend way more time re-explaining yourself than you would have spent documenting.

[finder83]

Do you have any advice or tools for diagrams? That's one area I struggle with, and usually have to pull in our designer.

[qznc]

PlantUML if you want to maintain the diagram in version control.

yEd for interactive use because of its auto-layout function. Not unintuitive to use though. It takes some effort to learn.

Enterprise Architect if your company pays the money and you really need its features (e.g. SysML diagrams).

Whatever is close by. For example, we use Confluence for our wikis. It has a Gliffy plugin, so I often use that for embedding diagrams.

I've seen photos of whiteboards, drawings in MS Paint, and other stuff. The tool rarely matters. What matters more is the content. A few tips for that:

Have clear meaning what a box means and what an arrow means. Don't make it inconsistent like "this box is a server, this box is a software component, and this box a message". If you need multiple types, then draw them differently (colors, rounded corners, dotted, etc).

One statement, one diagram. Don't make multiple statements in one diagram like "Here you see we send do more messages then necessary and you also see the undesirable coupling between Foo and Bar". Ok, there is also value in overview diagrams to show "everything" but those are for live use in discussions and not for documentation which should be understandable on its own.

[finder83]

Thanks!

[jugg1es]

draw.io (which is now app.diagrams.net) is all I've ever needed. I got my company to buy the Confluence plugin for it too. It's free to use by itself.

[shadowfox]

This is a great advice. Do you know of any publicly accessible design documents that you would consider good (to serve as An example)?

[dotdi]

Thanks, I feel this is great advice!

I used to insist on writing down the things that were just floating around in the heads of the more experienced team members, and it went really well for a time. I was part of the effort that pushed for better infrastructure for documentation, and we did get it in the end.

But, alas, this stalled and so did the excitement about having documents.

[awithrow]

> Part of the problem was - no kidding - I needed a new glasses prescription.

Huh, what did the glasses have to do with it? Old prescription making it hard to read text for long periods of time?

[artsyca]

Yes I've suffered the same - farsightedness making it hard to focus literally and a slight astigmatism where one eye focuses a little better than the other combine to increase fatigue and make prolonged writing very difficult

With glasses my whole mind relaxes and I can settle right into the zone

[squeed]

Yeah, same here. It turns out I could focus, but it took a lot of brain power to actually and understand text.

Getting new glasses lowered the cognitive load.

[stronglikedan]

Yes, and in my case, it's still hard to read text off a backlit screen, even with the right prescription. I have to use e-ink or paper if I'm going to be reading for a while.