Two quotes from the article stand out. First, from the X screenshot: "something about the process of writing makes your ideas 10x better". Second from near the beginning: "The most important person to convince is the author."

Design documents are so essential that even after mumble years in the industry, I am amazed when people, including putative "Product Managers" push back on the idea. As Leslie Lamport noted, "Writing is nature's way of telling us how sloppy our thinking is."

For those wanting to learn how to improve the quality of their technical writing, see Write Like an Amazonian: https://medium.com/@apappascs/write-like-an-amazonian-14-tip...

I sometimes even write design docs that will probably only ever really be read by me. It's so powerful to write these things down.

A example doc would of been really helpful, I'd love to compare the final structure of mine with others.

7.5 Years at Amazon, and even for my side projects, I write PRFAQs and share them with my stakeholders to gather feedback. I'm a PMT at Amazon, but in my alternative life, I code on many projects, and develop infrastructure, architecture, etc, and enjoy writing as much of it as I can.

That said, work back from your customer!

> work at a place with a writing culture

I would extend that to working at a place with a design culture. That is engineers prefer to work on projects that have been designed including a written plan before starting. And mistrust or avoid leaders that cannot plan in writing, and projects that have not been planned.

All of this, plus, writing the documentation before building the app. I remember a Dilbert cartoon making fun of this being about the time I started realizing Dilbert wasn’t as smart as I had thought.

If you can’t write the documentation before you’ve written the code, you don’t understand well enough what you’re building the code for.

It’s one thing to jump into code because it’s fun to write code. But writing code is not designing software, and vice versa.

Same goes for APIs. Writing docs for an API that doesn’t yet exist can help create a much more complete and coherent API.

This is why I’m often trying to help stakeholders understand that the vast majority of software development has very little to do with actually writing code.

Herein also lies a concern I have about AI assisted development. It can be a powerful aid to the design stages, and it can be a powerful aid to writing code, but I’m not sure it enables skipping the design aspects altogether and somehow coming up with a complete, coherent product.

As a design reviewer, I think all design authors should internalize this concept:

> But a good doc will lay out the problem and mental models in a way that the solution that took weeks of hard thought to invent will be clear to the reader by the time the doc presents it.

Perhaps my favorite quote is: "If I had more time, I would have written a shorter letter."

Design docs should make complex things simple. They should not be a dumping ground for all the intellectual hardships and false starts the engineer went through. It may still worth capturing this, but that should be in another doc, or at least an appendix. Keep the path forward simple and understandable.

I love docs written like this, and writing culture generally. But I've also seen something like this backfire a bit.

I think this approach is particularly good for docs where the assumption is the audience wants to understand why you reached the conclusions you came to, and the doc is sort of a persuasive argument. I think this is a valuable doc (and how I like writing and reading), but it is not always the case.

I think often you do want to start with the conclusion, the "end" so to speak, to orient the reader. And also to address the reader who trusts your judgement, and just wants to get up to speed. I've seen a lot of cases where the audience might not be ready/want to follow along w/ a train of reasoning, they want to know the punchline. And once they do, then they might want to follow up.

> Think of a design document like a proof in mathematics. The goal of a proof is to convince the reader that the theorem is true. The goal of a design document is to convince the reader the design is optimal given the situation.

We don't need to veneer technical writing in faux rigour for it to be worthwhile. That's the silly stuff that belongs on LinkedIn.

This kind of psuedo-rigor feels good to nod along to, but it's nonsense.

'We're not writing code, we're programming', 'we're not just programming, we're doing software engineering', and now 'we're not doing software engineering we're doing rigorous proof based mathematics' all of a sudden.

IDK how you write 'Think of a design document like a proof in mathematics.' without feeling at least a little bit silly.

> The goal of a design document is to convince the reader the design is optimal given the situation.

A proposed design may be optimal, or it may not, but the purpose of a design document is not to prove that the proposed design is optimal by any definition.

In a software development setting you're virtually NEVER formally proving anything, nevermind optimality.

You're writing technical fiction based in reality, nothing more. It's not a 'proof' of anything.

You're convincing stakeholders that your proposal can be feasibly built, is viable to run in the ecosystem of the rest of your codebases and infrastructure, and satisfies whatever business requirements that led to someone asking you to create a new $thing the design doc is aiming to propose the technical solution for.

Nothing more IMHO.

If your doc isn't doing those things then it's not effective, if it's giving the illusion of trying to do more than those things then it's just theatre.

The rest of the article is standard good writing advice, but can we not put design docs and PRFAQs on an altar as anything more than technical business fiction to communicate ideas and proposals for scrutiny to stakeholders.

Perfect for dragging into my context window :). Thanks!

That note in the tweets above, spoke to me.

I'm usually the only person that ever reads my docs, so I write docs for me.

I also often write design docs during, and sometimes after my projects.

I call it Forensic Design Documentation[0].

[0] https://littlegreenviper.com/miscellany/forensic-design-docu...

In my experience, organization/clarity is the biggest hurdle for SWEs trying to improve their doc writing. I like the author's spaghetti code analogy for the importance of idea organization within a doc -- I've struggled to convey the same concept before and I will use this in the future. In the past I've talked about 'ferrying' the reader through your thought process but this post explains the concept in a more familiar way.

I wrote a similar post last year[0] and it was interesting to see the similarities (concision, importance of practice) and differences with someone from a different company. I'm not sure I agree about 'short paragraphs' -- that may be a natural consequence of high information density writing but line breaks themselves aren't much help if the ideas aren't distilled. The 'Editing' section gets at that underlying idea more directly imo.

[0]https://ryanmadden.net/things-i-learned-at-google-design-doc...