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

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

That said, work back from your customer!

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.

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.

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

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.

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

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

Here’s a link to Harmel-Laws’post if anyone's interested: https://martinfowler.com/articles/scaling-architecture-conve...

I've never worked at Amazon, but I've heard this a lot, and it always strikes me as an odd practice. Odder still is that it apparently works and everyone I hear talk about it seems to love it.

You're squandering precious meeting time by having everyone sit and read a document together. They could easily do the same thing ahead of the meeting, and you'd have much shorter meetings.

And doing it synchronously means everyone either sits idle until the slowest reader is ready or not everyone gets to finish in time. And "slowest reader" isn't even just about reading speed. Presumably, some people can understand the document more quickly because they have more context.

In design reviews at Google, it was obvious that the majority of attendees came unprepared and were reading the docs for the first time while their teammates were discussing the doc. I suspect that the reason was that Google just didn't have a strong docs culture, and leads/managers quietly tolerated people coming unprepared (and sometimes, they themselves were unprepared).

I've never seen it done in practice, but I don't think it would be hard to have the best of both worlds where people review docs ahead of the review meeting, but there are strong cultural norms around reading docs ahead of time so the meeting is just for discussion, not just for reading or pretending that you've read.

Step 1. Brain dump into a doc (consider using dictation to get more thoughts down faster)

Step 2. Have an LLM give it structure & progression. You are ordering your thoughts for readability, so you'll probably want to throw it away. You're still refining your thoughts at this stage.

Step 3. Take the LLM output as a starting point, or write an outline from scratch. Flesh it out into a first draft

Step 4. simplify: cut words, swap big words for small words, etc.

Step 5. Repeat step 4.

LLMs bridge the gap from word-vomit to structure. You should be willing to throw away what you get from the LLM.

At least 30% can always be cut. It's amazing how much can be trimmed without losing the intent.

Hated this about Amazon; I need to be in a certain state of mind when reading technical prose which is hard to arouse on a whim. Happy to make and submit edits prior to meeting and then discuss. I also much prefer token passing when making modification of the document, rather than simultaneous people marking it up.