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."
I think this idea got so pervasive all throughout tech that all the resumes that i now get are filled with so many numbers that i don't even know what to make of them.
I and a few others really did save my company 10 million dollars one year. It was in EC2 spend for a hadoop cluster. I can tell you how we did it and who did what. Yes it was actual dollars we would have otherwise paid to AWS, it is not funny money calculated by looking at sticker rates and ignoring our discounts (which were large).
I'm proud of this and it was one of my largest impacts at the company. What would you have me put on my resume? "Decreased EC2 spend by a whole bunch!"? "Reduced EC2 spend"?
I don't get where this hatred of numbers on resumes is coming from. Is much of it probably bullshit? Yeah, just like most resumes. But I expect you to sort through it the same way you do the rest of the resume. Ask them about it. I can tell you the whole story of mine. I'd expect others can do the same. And if they stammer and crack, now you know how exaggerated it was.
You can complain all you want on here but it's not going to change the fact that most readers including myself just glaze over them. Because as you say most are just bullshit.
So keep doing it if you don't actually care. If you do, maybe try to think of a different way to communicate it that sets you apart.
I generally like it when resumes do this, and so do most people I know. I'd be interested to see surveys, I don't think it's anywhere close to universal. That said, I'm typically focused on very measurable domains (e.g. making code faster.)
99% of bullet points containing numbers in a resume are made up, hamfisted BS, the other 1% cannot be attributed to a single individual so putting them in a personal resume is silly.
I agree with the sentiment, but not the conclusion. Sure, numbers can be abused, just like anything else, but they provided specificity which you can then interrogate and call bullshit on. I won't necessarily fault someone for leaving off the numbers and just speaking qualitatively to the large scale system rewrite they did, but it's harder to evaluate whether such an effort was indeed warranted or was just a lateral move post-hoc rationalized by an engineer who didn't understand the original system and needed to rewrite it just to achieve that understanding. Again, if someone is satisfying the business with such efforts, more power to them. As a hiring manager, I don't want to get into a subjective evaluation of the relative engineering value of specific work at an external company that I have no first-hand context on, but I do want to know that candidates understand the highest level goals they are hired to contribute to. Metrics, however flawed, give a good entry point into such conversations.
I don’t blame people for doing so. That’s what they have been told by recruiters to do to increase their chance of their resume not being thrown into the trash or be invisible. If there is someone to blame for this, it’s the recruiting industry.
Not you specifically, but as an industry response, that seems too pat.
The recruiters will do and react to what the hiring managers ask for. When one too many candidates slip thru who bullshit, or there is weak signal that such and such method of candidate selection seems to result in marginally stronger candidates, then everyone rushes to do that thing and it eventually becomes sludge. Leetcode interviews are a classic example.
We (individuals) get poor candidates because we (industry) encourage and reward poor recruitment practices. Time for us all to look in the mirror, honestly.
I've seen 300k salary hiring managers punching down on a recruiter making 60k who doesnt know her C# from her C++. That sort of behavior says more about the flaws of the hiring manager than the recruiter. If you never talk to the recruiter but once a year when you have budget to hire someone, never take the time to educate them on your business, well then you're going to get crappy candidates.
It’s so dumb. There is no way to verify the numbers, and yet, this stupidity weaseled its way into the LinkedIn cinematic universe of corporate bullshit. The same point but without the “X by Y%” hits the same for me— besides I know what questions to ask to judge if you are actually capable of moving the needle, which is all I care about as a conductor of interviews.
the problem is CVs are screened by non-tech HR/recruiters, who lack the capacity to screen candidates. Because it is much easier to apply online with one click, each position is spammed with millions of CVs.
in response, for HR it is much easier to filter out CV if it lacks style, not substance. Therefore they look at bullet points like "Done X by Y%".
The proper way should be to limit the intake funnel: accept only a few applications per job, so that they can be screened properly by HRs by calling them, and talking to them and properly screening (old school style), instead of tossing their resume to the bin after 15 sec quick review
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.
Two questions I ask myself are "will I get bikeshedding around this?" and "is this worth bikeshedding about?" My goal is to make the most difficult ideas trivial to talk about for first time readers, while avoiding the problems I know don't matter but will get a lot of comments.
>Amazon meetings start with the presenter passing out copies... of a prose document... The meeting starts with everyone sitting in silence, reading the document, and adding notes and questions in the margins with red pen.
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.
> They could easily do the same thing ahead of the meeting, and you'd have much shorter meetings.
Amazon’s practice is a reaction to the fact that nobody actually does this. According to the article I read about this years ago, they realized that “creating a strong culture around reading before the meeting” also isn’t possible because many attendees had a meeting before this one, and couldn’t prepare for that meeting because they had a meeting before that, etc.
On paper you could punch a ton of holes in this: Why not reduce the number of meetings people have to attend? Doesn’t the reading reduce the amount of time available in the meeting to actually make decisions? But it would seem that in practice they found that the meetings people were attending did in fact have value, and that even with the reading time a lot of decisions got made.
So this may just be one of those things where you have to look at the results instead of worrying about what could theoretically be done differently. And it sounds like people really like the results and that the benefits of this approach outweigh the drawbacks, at least at Amazon.
>Amazon’s practice is a reaction to the fact that nobody actually does this.
But isn't that bizarre? I can't think of anything else where we need engineers to do something by a deadline, and we just resign to the fact that they won't do it unless we sit them in a room and babysit them while they do it.
> I can't think of anything else where we need engineers to do something by a deadline, and we just resign to the fact that they won't do it unless we sit them in a room and babysit them while they do it
Pretty much anything, unless you're in the engineer's management chain, or you've given them a direct incentive.
It's always been my experience in bigco that people can ignore almost anything that doesn't come from their management chain up until scheduled meetings get involved. Being uncooperative with meetings (declining invites without alternatives; not attending; not participating) are when escalations and complaints start occurring, and there seems to be a silent consensus that this is the standard - as in, if you complain that someone hasn't answered your emails, the standard response you should expect from anyone, including their manager, is "then schedule a meeting."
So, if you need someone to do something, you schedule a "meeting" to block time on their calendar in which they will pay attention to your thing. That includes anything they need to do to prepare, because anything you don't include in that time block isn't part of the meeting and therefore isn't going to get done.
The rule is not so much for the benefit of the kind of junior IC engineer who has time in his schedule to work on code, but for busy leaders whose experience of the world is otherwise 100% verbal.
Why does it matter when they read it? If they need more time for the meeting they can schedule more time. Only downside is that finding meeting slots becomes more difficult, but the total time spent doesn't change.
Solid advice on clarity and editing. The only gap is what happens after the doc is approved? Without upkeep it decays into "design archaeology." A few years ago, Andrew Harmel-Law wrote about an interesting approach to scaling architecture conversationally, which includes lightweight Architecture Decision Records (ADRs) as one tool that could help here. ADRs live beside the code (adr/001-use-postgres.md) and capture context, decision, and status in a format short enough to, I think, revisit in every PR and easy to supersede when reality changes so the original rationale stays searchable months later.
There are so many external links, it's easy to get lost in this article. Look under content for the section titled "1. A Thinking and Recording Tool: Decision Records." It's under "The Four Supporting Elements." Here's a direct link if it's easier https://martinfowler.com/articles/scaling-architecture-conve... (Just search on that page for "The Four Supporting Elements)
There Harmel-Law defines ADRs as "lightweight documents, frequently stored in source code repositories alongside the artefacts they describe." He also provides a handy "Elements of an ADR" table. Let me know if you're still having problems finding it.
This is the case with Session messenger. It's been so many design and architectural changes that there's no single place that is authoritative of how it operates and works.
Btw use Signal if you want secure messaging, full stop.
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.
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.
Taking a class in technical writing greatly improved my ability to summarize written documents. The course emphasized a “cut with a red pen” approach (write, cross out, rewrite), which focused on using as few words as possible to communicate concepts and ideas clearly. This method has multiple layers and becomes easier with practice. I also try to share this knowledge with the teams I work with, but it’s important to remember that it’s a skill that requires regular training.
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.
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.
I also added an Appendix "Technical Stack Considerations," but I like the PR and the FAQ's to focus on the customer/end-user's needs. The technical details matter, but they serve the customer outcome, not the other way around.
A recent project's tech appendix had headers like "Core Technology Philosophy", "Backend Architecture", "Frontend Architecture", "Service Architecture", "Infrastructure and Deployment", "Security Architecture", "Performance Requirements", "Configuration Management", "Backup & Disaster Recovery", "Development Workflow", "Network Architecture", "Resource Management", "Development Principles", and "Scalability Considerations".
The beauty is that by the time you get to the technical appendix, you've already validated what you're building and why it matters. The technical choices then flow naturally from the customer requirements rather than driving them.
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.
The meeting starts with everyone sitting in silence, reading the document, and adding notes and questions in the margins with red pen. Watching people mark up the document you spent so much time polishing is a strong forcing function to become a better writer.
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.
Actually, I often find that old Slack conversations can be the most helpful representation of how a program works in real life and how to troubleshoot it and workaround its shortcomings. The official documentation is often too concerned to be concise and "pure" (OP compares it with a mathematical proof) so it only represent an idealized version of a software that didn't ever exist.
I do like discussing things after the fact. I think a "proof" is a good starting point, and if you don't start with at least that, then jumping into a slack conversation to do that foundational work causes problems.
I really like a PR as as the place to put the proof: you can only assume it is true for that moment in code, and it is associated with that. Of course it isn't remotely true as all software has bugs, but at least it can be a concise statement of how you understood it at the time, and that's valuable. The author is noting that you need to get into the mental model of the author, and this is a good place to capture your thinking.
I think READMEs for a repository, in general, are almost always worthless and outdated, like you allude to.
At my company, we went from using detailed RFCs to one-pagers, and eventually to writing no formal docs at all. Over time, RFCs turned into artifacts optimized for promotions rather than alignment or clarity. In many cases, people ended up spending more time crafting the perfect document than actually implementing the solution.
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.
> 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.
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 think this idea got so pervasive all throughout tech that all the resumes that i now get are filled with so many numbers that i don't even know what to make of them.
N.B. I received such a resume while typing this comment and am absconding to Outer Mongolia as I type
I and a few others really did save my company 10 million dollars one year. It was in EC2 spend for a hadoop cluster. I can tell you how we did it and who did what. Yes it was actual dollars we would have otherwise paid to AWS, it is not funny money calculated by looking at sticker rates and ignoring our discounts (which were large).
I'm proud of this and it was one of my largest impacts at the company. What would you have me put on my resume? "Decreased EC2 spend by a whole bunch!"? "Reduced EC2 spend"?
I don't get where this hatred of numbers on resumes is coming from. Is much of it probably bullshit? Yeah, just like most resumes. But I expect you to sort through it the same way you do the rest of the resume. Ask them about it. I can tell you the whole story of mine. I'd expect others can do the same. And if they stammer and crack, now you know how exaggerated it was.
So keep doing it if you don't actually care. If you do, maybe try to think of a different way to communicate it that sets you apart.
The recruiters will do and react to what the hiring managers ask for. When one too many candidates slip thru who bullshit, or there is weak signal that such and such method of candidate selection seems to result in marginally stronger candidates, then everyone rushes to do that thing and it eventually becomes sludge. Leetcode interviews are a classic example.
We (individuals) get poor candidates because we (industry) encourage and reward poor recruitment practices. Time for us all to look in the mirror, honestly.
I've seen 300k salary hiring managers punching down on a recruiter making 60k who doesnt know her C# from her C++. That sort of behavior says more about the flaws of the hiring manager than the recruiter. If you never talk to the recruiter but once a year when you have budget to hire someone, never take the time to educate them on your business, well then you're going to get crappy candidates.
in response, for HR it is much easier to filter out CV if it lacks style, not substance. Therefore they look at bullet points like "Done X by Y%".
The proper way should be to limit the intake funnel: accept only a few applications per job, so that they can be screened properly by HRs by calling them, and talking to them and properly screening (old school style), instead of tossing their resume to the bin after 15 sec quick review
> 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'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.
Amazon’s practice is a reaction to the fact that nobody actually does this. According to the article I read about this years ago, they realized that “creating a strong culture around reading before the meeting” also isn’t possible because many attendees had a meeting before this one, and couldn’t prepare for that meeting because they had a meeting before that, etc.
On paper you could punch a ton of holes in this: Why not reduce the number of meetings people have to attend? Doesn’t the reading reduce the amount of time available in the meeting to actually make decisions? But it would seem that in practice they found that the meetings people were attending did in fact have value, and that even with the reading time a lot of decisions got made.
So this may just be one of those things where you have to look at the results instead of worrying about what could theoretically be done differently. And it sounds like people really like the results and that the benefits of this approach outweigh the drawbacks, at least at Amazon.
But isn't that bizarre? I can't think of anything else where we need engineers to do something by a deadline, and we just resign to the fact that they won't do it unless we sit them in a room and babysit them while they do it.
Pretty much anything, unless you're in the engineer's management chain, or you've given them a direct incentive.
It's always been my experience in bigco that people can ignore almost anything that doesn't come from their management chain up until scheduled meetings get involved. Being uncooperative with meetings (declining invites without alternatives; not attending; not participating) are when escalations and complaints start occurring, and there seems to be a silent consensus that this is the standard - as in, if you complain that someone hasn't answered your emails, the standard response you should expect from anyone, including their manager, is "then schedule a meeting."
So, if you need someone to do something, you schedule a "meeting" to block time on their calendar in which they will pay attention to your thing. That includes anything they need to do to prepare, because anything you don't include in that time block isn't part of the meeting and therefore isn't going to get done.
Here’s a link to Harmel-Laws’post if anyone's interested: https://martinfowler.com/articles/scaling-architecture-conve...
"That’s it. That’s the Advice Process in its entirety." (speak to everyone involved).
Presumably anyone with the term Managing as a prefix in their job title is expected to glaze over at roughly this point.
Then we get to the meat: "The four supporting Elements". So I try to find out about ADRs:
I follow the first link:
https://www.thoughtworks.com/radar/techniques/lightweight-ar...
and eventually end up with this beauty (big download button at the bottom of the page from above):
https://www.thoughtworks.com/content/dam/thoughtworks/docume...
Would you mind pointing us at an actual definition of ADRs, please?
There Harmel-Law defines ADRs as "lightweight documents, frequently stored in source code repositories alongside the artefacts they describe." He also provides a handy "Elements of an ADR" table. Let me know if you're still having problems finding it.
Btw use Signal if you want secure messaging, full stop.
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.
Then somebody comes along and asks about something specific, so you expand.
Finally they use an LLM to compress after their pet idea was satisfied.
It’s crazy really, we’re just on a never ending rollercoaster here.
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...
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.
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!
A recent project's tech appendix had headers like "Core Technology Philosophy", "Backend Architecture", "Frontend Architecture", "Service Architecture", "Infrastructure and Deployment", "Security Architecture", "Performance Requirements", "Configuration Management", "Backup & Disaster Recovery", "Development Workflow", "Network Architecture", "Resource Management", "Development Principles", and "Scalability Considerations".
The beauty is that by the time you get to the technical appendix, you've already validated what you're building and why it matters. The technical choices then flow naturally from the customer requirements rather than driving them.
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.
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.
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 do like discussing things after the fact. I think a "proof" is a good starting point, and if you don't start with at least that, then jumping into a slack conversation to do that foundational work causes problems.
I really like a PR as as the place to put the proof: you can only assume it is true for that moment in code, and it is associated with that. Of course it isn't remotely true as all software has bugs, but at least it can be a concise statement of how you understood it at the time, and that's valuable. The author is noting that you need to get into the mental model of the author, and this is a good place to capture your thinking.
I think READMEs for a repository, in general, are almost always worthless and outdated, like you allude to.
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.
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.