The structure I prefer for a technical design document is like a three-layer onion.The first layer is the problem statement, goals, non-goals, and requirements, both functional and non-functional. The next layer is the functional specification, which describes precisely how the system will work from an external perspective. The third and final layer is the technical specification, which describes the internals.
Each section should follow from the previous. The design doc should justify to the reader (and author) that the problem is understood, the requirements are necessary and sufficient, the functional spec meets the requirements, and the technical spec implements the functionality and non-functional requirements.
As a corollary, if one section has a fatal flaw, there is no need to read on. If the problem is misunderstood, then the functional spec is likely wrong. If the functional spec doesn't meet the requirements, then the implementation is moot.
The issue I see very frequently is technical design documents that provide only the final section—a simple description of the system that will be built. As a design reviewer, there is limited feedback I can provide on such a design. Sure, it's a system, but will it solve the problem? Does the team even agree on the problem to be solved?
Layer one also explicitly identifies stakeholders, and describes the current (AS-IS) situation with annonated screenshots so everyone quickly sees what we are talking about.
Layer two also lists alternative solutions considered and why not chosen.
Layer three is developers making a few notes on chosen tech design, most important is the choice reasoning here.
In all layers, add and use references. Less is more, a picture beats a wall of text.
Yes, agree with all of that. I don't think every design doc needs every possible section, but if readers would benefit from the background or the an enumeration of stakeholders, that belongs up front, before the design.
To add a little more color, each section also has a branch of possibilities. Given a problem, there are many possible functional specs that could solve it. Given a functional spec, there are many possible implementations. The act of choosing from among these possibilities is designing and the design doc should lay out the choices made (and sometimes the choices not made) and why.
In IT, it's all virtual, so in theory anything is possible. Setting hard limits is necessary, or else the solution space is overwhelming, and the second system effect can kill your project (even in the first system!)
In mechanical or electrical engineering, some potential goals are blatantly physically or economically impossible and do not need to be mentioned as non-goals.
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.
I've only been a hiring manager once, and it was for a junior-level position so take that into account.
When I read resumes, accomplishments meant next to nothing to me. I was looking for capabilities.
Your EC2 example is probably an exception to what I'm about to say because EC2 is very well known and you can quantify the difference you made in real dollars. But, 99% of the time I have no frame of reference and therefore no way to evaluate claimed accomplishments on a resume.
Oh, you managed accounts totaling $24MM in accrued receivables annually? Sounds impressive, but what if every one of your peers were managing $30–40MM and you were well known to be a slacker? Etc.
It's much more useful to me to know what classes of problem you can solve and which tools / techniques / technologies you're proficient with toward solving them. Descriptive statistics do very little for me.
> and you were well known to be a slacker?
> what classes of problem
If people are going to lie on their resume there isn't a whole lot of anything you can do to fix that at the resume evaluation level. So many resumes have 100x skills where they say they know some language because they happen to walk by a room where someone might have been looking at the wikipedia page describing someone who might have used the language once accidentally.
If you can't relate the impact / accomplishment of the candidate for your job to your company,then that just speaks to a low quality resume. It should be obvious to any reviewer why what you did is relevant to their interest.
The reason why impact matters is that in some sense it should be theoretically reproducible. "Saved 100s of engineering hours by fixing some nonsense" which if true should speak to someone who can ostensibly save time while also understand the meaning of their work.
Not sure about the author, but having a few hundreds interviews under my belt (as the interviewer) some of those statements are incomplete.
Your example is complete, but if I see statements like: "decreased latency by 5%" I will ask you if are we talking about median or long tail latency. Another example would be "developed a ML model that increased revenue by X%". Here it is missing how the population is affected. If you say overall then I will ask you things like: "For which slice of the population did you see the biggest improvement with the new model? Any regression?" or "Did you run any control group".
While I might or might not care about the technicalities of your answer the important thing is that if you can't convince me that you know what you are talking about then it is as parent said, bullshit and I will stop likely paying attention to you and mind my business as I will suggest a no-hire.
If, instead, it looks like you really did those things you mentioned it is a nice ice breaker and genuine candidates seem to perform well when they get the tension out of the way by answering something they know.
PS: If I were to interview you I would ask "How" because as I mentioned it is a complete statement in my mind :)
No, but hints work. Like the latency one adding "on p99" makes me think it is a specification that adds a lot with just 2 words and the credibility weight it adds is huge (IMHO).
That's a good example for a success. I've seen resumes from Junior devs with <2 years experience, where every line item was a business goal met, and almost nothing on their technical skills they've gotten. Been a hiring manager 10+ years, and it's a trend I've seen more recently.
If you try to impress a technical interviewer then they will be more interested in the smart idea you had and how you implemented it rather than how much money it made.
It's perfectly fine. The important part is that you can explain during the interview what you did to achieve that impact and demonstrate the skills. A lot of BS ends there. I never threw out a CV because it contained too many numbers or it was too precise. Quite the opposite. I flag CVs that are too vague and use big words without facts often repeatedly but do not provide much information.
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.)
I've read so many resumes over the last few years that I'm just completely overwhelmed by the practice. In fact I now judge resumes unfavorably if they use it more than very sparely.
The best resumes I read (and the strongest candidates) were ones which were very confident in their skills and experience. They showed a bit of personality (as much as you can).
I do feel bad for junior developers. I'm at the point where I won't consider a job unless it came through my professional network. I did a bit of job hunting during some downtime after my last gig just to be diligent while my current was being lined up and it is utterly depressing. LinkedIn and co's "one click apply" has to be the worst thing to happen to the industry for remote workers.
Back in "my day" you'd tailor your resume to the company you applied to in an effort to highlight relevant experience, and that was a minimum- most also included a cover letter... Not fire off three dozen applications a day hoping to hear back from one after a month or three.
I often read “decreased X by N%” as a slight lie: they don't tell how precise N% was measured and how they can know that all of N% came from their work and not other circumstances.
So my impression is that they work sloppily and oriented more towards office politics than good engineers.
Presenting such numbers to motivate management is a frequent advice on the Soft Skills Engineering podcast [0]. I agree that their (the numbers’) meaningfulness is often doubtful.
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.
> The goal of a design document is to convince the reader the design is optimal given the situation.
This is a nitpick, but I don't think the goal of a design is to be optimal so much as sufficient.
Software systems design, like any design, is about coping with constraints and tradeoffs. The design doc should clearly lay out these out and present an approach that meets the requirements and constraints with acceptable tradeoffs. Where multiple reasonable alternatives exist, they should be make explicit along with a justification for why one option was chosen over the others.
Will it be perfect? Probably not, unless it is an easy problem or you over-designed. And even if it's a good design, it can hit unforeseen issues during implementation. The goal of design is not to eliminate all possibility of such issues but to mitigate risks and communicate to the stakeholders what we're building and why we're building it that way.
Isn’t “making acceptable tradeoffs” (optimization) while “meeting requirements & constraints” (under constraints) simply optimization under constraints? I fail to see how this is about sufficient _but not optimal_ solutions.
The dictionary defintion of optimal is just 'best'; the connotation that 'optimal' means not perfect, but satisfying multiple constraint, is engineering jargon. In fact, with 'optimal', people will often mean 'Pareto optimal' (a design where there is no change that would improve the solution on all dimensions/constraints).
Pareto optimality also implies that multiple designs may exist in a 'draw', where design 1 is better on dimension A, but worse on dimension B, and design 2 flips those. These designs are on a pareto front. Making the trade-offs explicit helps readers of the design document who come along later to choose a different trade-off when it later turns out that the relative importance of the dimensions involved changed.
I generally read "optimal" to mean "optimal according to some objective function". In the case of a technical design, the objective is not something you can readily formalize, because there are so many considerations.
For example, suppose you are designing a network service to meet some use case. Yes, it needs to meet the use case, but there are other things you care about like simplicity of the code, latency, cost to operate the service, and others.
For any design you propose, there might exist an alternate design that is strictly better by some criteria-maybe it works exactly the same but has much better latency characteristics. If an oracle gave you this design, you might agree it was more optimal and choose to implement it, but I don't think it means you failed if you come up with a (sub-optimal) design that solves the problem within the constraint.
It's also not intended to be frozen in place and some allowance should be made for refinement with out scope breaking (fine but falls under change control) -- the level of detail here is important so known unknowns are surfaced not solved. High Level Designs and Low Level Designs are different documents for a reason allowing for a sufficient approach to be optimized during the transition.
"Optimal" in this context includes time, effort and cost. So the design isn't perfect irrespective of these things, but it is optimal in terms of balancing the effectiveness of the solution with the effort put in.
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.
Then do Security, Privacy, Compliance, and the review committees of all affected orgs become blocking reviewers on any PR that touches an ADR? Are these PRs getting merged in less than 90 days?
Fair point about process bloat. Just to clarify: I'm not an ADR expert nor do I personally know Harmel-Law. Just deriving insights from his blog post that I linked to earlier because I thought it was interesting.
But, I think you might be picturing ADRs as heavier than they need to be. Most changes seem like routine updates ("We decided Postgres" → "We're migrating to Aurora") that go through normal code review. The big architectural shifts that would trigger Security/Compliance review probably should anyway, ADR or not.
The key insight is that ADRs document decisions, they don't create them. If a change is big enough to need committee review, it likely needs that scrutiny regardless of whether there's documentation.
The alternative, undocumented drift, often creates much longer delays when people rediscover decisions during incidents. Curious to hear from folks who've actually implemented this at scale, though.
>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.
In my experience there is always more work to be done than there is time. That means people have to start prioritizing things, managers breathing down necks over specific things is a priority signal, just like meetings. Reading something doesn't give you much actual production output to show for, so it just doesn't get prioritized.
Then you should schedule two meetings: one in a reading room, at any time that fits each individual calendar, and then later the real one in a meeting room with everyone's involved, at the same time.
We all know the costs of context switching. Why would you unnecessarily introduce two new context switches? Is it because you don't like being told when to read?
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.
> 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.
This is practically the point of meetings. Meetings exist as a forcing function to achieve communication that likely could have happened asynchronously but for some reason didn't.
I disagree. I think companies that have meetings like this have an immature meeting culture.
Meetings are for low-latency collaboration, not information transfer.
For example, reading a design doc is obviously more efficient asynchronously because everyone has different reading speeds and doesn't need everyone else in the room while they read.
Arguing about tradeoffs in a design doc is usually more efficient in a meeting than an email because the low latency communication and additional signals from live communication make the discussion more efficient. For example, if the design doc says we should do X but you think it should do Y, in an email I maybe have to enumerate all the advantages and disadvantages, but in a meeting, maybe you're convinced after seeing just 20% of my rationale.
> For example, if the design doc says we should do X but you think it should do Y, in an email I maybe have to enumerate all the advantages and disadvantages, but in a meeting, maybe you're convinced after seeing just 20% of my rationale.
This is organizationally inefficient. You should write these reasons down in the design document so that you do not need to rely on both of us still being employed 5 years from now to explain to someone who is evaluating the state of the system on why the decision was made. A design document must include justification, not just the final decision, -- that's obvious from the code.
What you're describing as "immature meeting culture" I would instead describe as "mature documentation culture". Different companies work differently of course, and if you're absolutely optimizing for latency and have relatively small groups of stakeholders, meetings are super efficient since you can make all decisions now. But if you're optimizing for throughput and have larger groups of stakeholders, more asynchronous (or entirely asynchronous), document/slack/email driven approaches.
I think the amazon approach is weird and somewhat childish, but I stand by "meeting is only necessary if the stakeholders haven't approved your design offline/async". For such meetings you can use the amazon approach, or you can assume folks have already reviewed and left open comments, and only address outstanding comments during the meeting.
I agree you should document the decisions and discussions around them. I never said you shouldn't, just that the discussion shouldn't be entirely written. But you can discuss live and summarize the discussion in the doc after.
Relatedly, I don't think full discussions about the design doc should live forever in the design doc. When I was at Google, I hated reading design docs where every line had a convoluted, 20-message comment thread attached to it in the margins. When I owned a doc, I'd drive those comment threads to a resolution, write up a concise summary of the debate in the appendix, then resolve the thread.
> Relatedly, I don't think full discussions about the design doc should live forever in the design doc. When I was at Google, I hated reading design docs where every line had a convoluted, 20-message comment thread attached to it in the margins. When I owned a doc, I'd drive those comment threads to a resolution, write up a concise summary of the debate in the appendix, then resolve the thread.
Yes exactly, you don't need the entire back-and-forth, but the relevant information should be written down somewhere.
> Meetings are for low-latency collaboration, not information transfer.
Ok, but without a doc, collaboration in a meeting can become inefficient in many ways. Folks can talk past each other, bouncing between unclear options and losing clarity on what they are even debating. Only one person can talk at a time, so folks are sitting and waiting for their turn, etc.; Strong personalities can dominate and filibuster.
Writing even a bad doc ahead of time can help to make the meeting’s purpose clear. The author can guide the discussion by laying out and labeling big options and decision points.
While reading the doc, everyone can comment in parallel, so you aren’t serializing the conversation for small things or letting some verbose person waste the time.
Reading during the meeting helps folks manage time outside the meeting. It means: you don’t have to prepare for meeting you don’t own. It avoids “random people” assigning you work beyond what they are asking you for in your calendar. For busy managers this is a huge benefit.
I'm arguing for reading the doc ahead of time, identifying topics about the doc to discuss, then coming to the meeting with a specific agenda.
>Ok, but without a doc, collaboration in a meeting can become inefficient in many ways. Folks can talk past each other, bouncing between unclear options and losing clarity on what they are even debating. Only one person can talk at a time, so folks are sitting and waiting for their turn, etc.; Strong personalities can dominate and filibuster.
I don't understand. These are just problems with meetings in general no matter what you do in advance. What are you arguing for?
>While reading the doc, everyone can comment in parallel, so you aren’t serializing the conversation for small things or letting some verbose person waste the time.
>Reading during the meeting helps folks manage time outside the meeting. It means: you don’t have to prepare for meeting you don’t own. It avoids “random people” assigning you work beyond what they are asking you for in your calendar. For busy managers this is a huge benefit.
I don't understand how this can be possible. It means that letting someone else manage your time is more efficient than managing your own time.
If I need 5 minutes to read a document, how is it helpful for someone to force me to sit for 10 minutes to read it at a specific time? It's obviously more efficient for me to read it in the block that I choose and not waste the extra 5 minutes.
The Amazon way sounds like how you'd manage time for a child, where you can't trust them to manage their time, so you have to schedule time blocks for coloring, recess, and eating lunch.
> I don't understand. These are just problems with meetings in general no matter what you do in advance. What are you arguing for?
That by simply requiring a doc, you have forced the person who called the meeting to think about what they want to achieve, and to prepare their thoughts ahead of time. This makes the agenda clear to everyone and helps to guide the discussion.
> It means that letting someone else manage your time is more efficient than managing your own time.
If we are reading the doc together in the meeting, I only need to accept/decline the meeting and I am good.
If I am expected to pre-read, I have to actively do something to schedule that pre-read time. And the doc has to be ready whenever I decide to read it. Multiply that by 10+ meetings a week for a busy manager, and you have a lot of mundane scheduling work to keep straight.
> If I need 5 minutes to read a document, how is it helpful for someone to force me to sit for 10 minutes to read it at a specific time?
I’ve not found that to be a problem in practice. I can use extra time to think and prioritize my feedback, or catch up on Slack, etc.
I've been in companies that do this. I like it more than alternatives.
The default for most meetings everywhere I've seen is to present information during the meeting, verbally or in powerpoint. For example, standups often devolve to people sharing their updates. This is much worse than having people write down updates and taking a few minutes to read them at the beginning.
Also note that these documents usually take about 5 minutes to read, even for slow readers. Meetings with much longer documents are pretty rare in my experience - feedback on long documents is usually done separately.
It would theoretically be better for people to read the documents ahead of time. But the benefit is pretty small IMO, and the cost is large – it fails if even a single person hasn't read the document.
I worked at a company where we copied this from Amazon for a specific type of meeting (bi-weekly review). But we also had the other "normal" type of meeting.
People never read the documents before the meeting in those "normal" meetings.
The challenge with your suggestion is that people will half-ass the doc reading before the meeting - we tried doing this for the "normal" meetings. It was obvious the people skimmed the doc before the meeting. You're also now relying on the manager (if there even IS one for everyone in the meeting!) to care about this.
So, in practice, giving people dedicated 10 minutes at the start of the meeting works far better.
Besides, in most "normal" meetings, the main presenter often ends up discussing background / context for 10 minutes interspersed throughout the meeting anyway. In the "pre-read" meetings, you're just compress that to the first 10 minutes while increasing the amount of information transferred.
> 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.
People don’t read ahead of meetings, and that results in wasting time discussing things already covered by docs.
> They could easily do the same thing ahead of the meeting, and you'd have much shorter meetings.
There's no difference in the amount of time spent whether it's read in or out of the meeting. At least spending the time in the meeting to read it, people are more focused on the topic at hand and the time will be better spent. Besides, I'd bet the fraction of those docs that are ready sufficiently ahead of the meeting are in the single digits.
They could easily do the same thing ahead of the meeting, and you'd have much shorter meetings.
To highlight two ways to go about this, we can assign homework, or assign, for lack of a better word, meetingwork. We don't always know how much free time our colleagues have outside of the time we've scheduled for a meeting. At least by enforcing meetingwork org-wide, it is ensured that everyone has at least some time to read the docs and they're fresh in their mind, even on short notice.
You're right about "reading speed", but I think the common alternatives are no one knows how prepared anyone is vs a few people might not be fully prepared.
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.
In addition to the reasons already listed (slowest reader etc) it's also good, at leasdt for some, to let new information sink in before discussing it.
I suspect these are not real issues. Most people smart enough to be an engineer read fast enough to finish 6 pages in 15 minutes(and your doc is bad if they can't), and discussing it fresh is probably better since you forget less.
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 often come across tips/pointers/exhortations about how to write good design documents. I generally agree that it's an important step: not just for clarifying your own thinking, but also for communicating effectively with others.
However, these types of posts often lack are concrete examples of what a good design document actually looks like. I understand that many of these documents are proprietary and intended for internal use. Still, are there any examples of well-written design documents available publicly that learners can study to get a clearer idea of what one should look like?
> However, these types of posts often lack are concrete examples of what a good design document actually looks like
The entire post is an application of his document designing philosophy. It became obvious with his first header being "Goal" and him mentioning to set a goal early on.
This should grow from within yourself. Read a lot of design docs and blog posts and articles and books. Which ones did you like? Which were confusing? And why was that? Was it the language complexity? Length of explanations? Diagrams? Too much / too little reasoning? Did you feel that the writer did a good job of picking you up were you were and brining it to a new state which now was enriched with their idea?
Constantly ask youself whether you liked a particular piece of writing and that will over time shape your understanding of what's good and what's not. Note that that's not entirely objectively quantifiable and people will have different tastes. That's also why it's hard to have a "good examples" archive because, just like with code, that would immediately people to start debating. But there is a certain core of properties most people can agree on.
Somewhere in some comment antirez said he writes design documents for his projects before he writes a single line of code. You can browse his GitHub projects or google “antirez design documents” or “antirez specification”.
Yes this is also a question that comes to my mind. Where are the design docs from the past 50 years of software development. There must be something concrete for people to study and learn from.
I've been doing this stuff for 40 years and spent the first 20 or so looking for design documents (having been asked to write many). Eventually I realized there are none. At least almost none, and very few that existed prior to the related software being written.
A design can evolve over time, but a design document's objective is to document what was going to be built at that time. If something changes, make a new design document. (Similar to blog posts or news articles, they also don't evolve over the years. You write a new one.)
It sounds like what you mean is system documentation, a handbook of sorts, and that's what needs maintenance. But that's different from a design doc.
Without fail, people who say this really mean "I am unable or unwilling to put in the hard work at the design stage to resolve uncertainty and will instead push these problems downstream to the development process where hopefully no-one will remember I'm responsible for the ensuing mess".
Yes, that's correct. In other words, my cost-benefit analysis concluded that shipping fast and iterating later is a much better strategy than spending countless manhours on plans and meetings in order to provide a product that is perfect from technical perspective but misses both the timing and market needs. I don't understand this fetishation of "perfect code" when experience shows again and again that for most use cases, the correct approach is to ship fast and fix later. We're not sending a spaceship to Mars, we're making an AI-based social media app, either we ship this week or next week facebook will launch its own version which will make our product completely irrelevant and being first to release a feature is the only way to capture a statically significant part of the market. As long as the most common use case works we're grand, if 80% of the app doesn't work that's fine because 80% of the users only use the main 20% of the app, and the focus is on making sure that this works correctly.
> I don't understand this fetishation of "perfect code" when experience shows again and again that for most use cases, the correct approach is to ship fast and fix later.
You're conflating two separate issues, because design documents help you ship faster and fix later. They do this by making you think about what you're building, thereby allowing you and downstream consumers of the plan to focus on a smaller and more valuable set of goals.
Your approach is the opposite - building by gut feel and ignoring the available data. That's leads to wasted effort and elongated development cycles.
> my cost-benefit analysis
You don't plan, so you don't know your costs or benefits.
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.
I feel like the process of editing my own stuff is at least as important as getting it down. That's when I go back through it and realize all the conclusions I leapt to, things I didn't thoroughly consider, and other flaws. I think people really undervalue writing as a focus tool. But maybe that's just me, YMMV.
I think the same thing about a lot of code, too. Sometimes you really are just hammering out boilerplate. But a lot of times even writing test code is a great opportunity to realize the main code could be improved. But the LLM probably won't tell you that.
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.
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.
This article is written front-loaded with vague ideologies, basic mostly-intuitive foundational concepts followed by a random mishmash of general tips. I was hoping for a more applied and structured tour with effective examples that work for common classes of problems.
A reasonable starting place: The best design document conveys the critical aspects, requirements, and relevant information in a way the audience will understand and be able to further reason about.
p.s. Sorry for the complaint, I was a bit disappointed because this is potentially a really interesting subject! Why does cargo-cult content get such good traction so consistently? Cargo-cult driven design leads to some odd outcomes IME. Sigh
Logistically speaking, is there a good hosting service for design docs but have google docs-like functionality to be able to comment and share feedback? I increasingly use tools like cursor to iterate on design docs that are in markdown format and currently I move things over to google docs manually and when there is feedback, I need to go back to cursor which creates a slow and weird loop. Have people identified better structures/processes for this?
We use Notion and most people seem to like it. I find it quite quirky but it does a good job of allowing comments and feedback that can then be marked as "resolved".
I'd probably prefer a pure markdown solution but I'm not aware of one.
I'm broadly in favor of RFCs but they need to be dictated from top-down. That's easier said than done.
Most RFC committee debates ime devolve into firing squads in which the presenter needs to answer every question with pin-point accuracy and perfect context from the asker. Otherwise, they look unprepared and the RFC is negated.
This is allowed to happen because everybody is a theoretical co-equal in the process. Thus, everybody wants to have their say. You'd hope people would read ahead of time but there's always somebody who doesn't yet feels entitled to ask pre-emptive questions. It makes for very combative discussions.
The exception is when a double-skip manager stops that from happening and lets the presenter "make their case" and walk through the whole RFC.
> ... sketching out that API is usually a good idea. In most cases, however, one should withstand the temptation to copy-paste formal interface or data definitions into the doc as these are often verbose, contain unnecessary detail and quickly get out of date.
Using R Markdown (or any Turing Complete documentation system), it's possible to introduce demarcations that allow the source code snippets to be the literal source of truth:
The documentation now cannot ever go stale with respect to the source code. If the comments are too verbose, simplify and capture implementation details elsewhere (e.g., as inline comments).
In one system I helped develop, we were asked to document what messages of a standard protocol were supported. The only place this knowledge exists is in a map in the code base. So instead of copy/pasting that knowledge, we have:
This snippet is parsed into an R dataframe. Another function converts dataframes into Markdown tables. Changing the map starts a pipeline that rebuilds the documentation, ensuring that the documentation is always correct with respect to the code.
If a future developer introduces an unparseable change, or files are moved, or R code breaks, the documentation build pipeline fails and someone must investigate before the change goes onto main.
Shameless self-plug: The R Markdown documentation system we use is my FOSS application, KeenWrite; however, pandoc and knitr are equally capable.
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.
> This disappoints the ego-seeking behavior of many engineers. Good engineers often want people to realize how clever they were.
This is probably partly true to a small extent, but for the most part I think it trivialises a larger problem.
I have had this exact problem as an academic publishing papers. My ability to write straightforward easy to follow manuscripts has backfired on me many times, whereby explaining the steps in a clear, intuitive order has led reviewers to state that the findings were non-novel since they were a clear intuitive series of logical steps. My (sad) experience has taught me that if you make the reader 'work' a tiny bit towards developing the intuition themselves, and appreciate how this specific sequence of steps wasn't necessarily trivially obvious before announcing it on paper, then they will appreciate the novelty and the thinking that went behind it a lot more.
Obviously I don't necessarily think the mass of obfuscated papers out there are academics intentionally obfuscating to prevent rejection and raise appreciation in their readers (it's more likely to be a lack of skill or interest in investing the effort to write more clearly). But (despite it's frequent abuse as a phrase) leaving _some_ things as "an exercise to the reader" turns out to not always be the 'lazy' or 'ignorant' thing to do.
Now, of course, design documents may not necessarily have the same goals or gatekeepers as academic papers do, but I think attributing leaving some steps up to the reader to be entirely about engineering ego-seeking behaviour is a bit misguided. If your goal is to make someone understand and appreciate something, then there is such a thing as "explaining it too much" (and thus robbing them of the experience of developing their own, and far more useful, insight).
And this is doubly true in teaching contexts (arguably not the usual purpose of a design document, but ...).
Let me illustrate a common code organization issue some programmers run into on their first day. The novice writes
terminal.print("Hello world")
Then they decide they want to make the text red, so they edit their program to
terminal.print("Hello world")
terminal.setPrintColor("red")
And then they're confused that it didn't come out red. They haven't internalized that the first line of code happens before the second. They just get a soup of code on the screen that kind of has the ingredients for a program, and expect the computer to do what they want.
I should write a lot more, but the two paths I see are: B.O.O. and Good Strategy/Bad Strategy.
B.O.O.: Background, Objective, Overview. Basically, a history lesson for how you got here, an objective for what you want to fix/change, and an overview of how you'll implement that change.
Good Strategy/Bad Strategy: An amazing book, but the organization is similar to boo. Problem Diagnosis, Guidelines/Assumptions/Requirements, and Actions.
I find BOO is better for targeted design documents in a google-like culture where you should write up a design document for almost any architecture change. The Good Strategy/Bad Strategy method scales pretty amazingly up to almost anything, but you need to be a much more experienced author to get things to fit it.
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.
Engineers have used drawing for millennia and yet software developers seem to be completely unfamiliar with them. A good drawing will help people visualize the problem in an instant, and let people talk about the different options much more easily.
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.
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.
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.
Oh, I interpreted design documents as general things - documentation included.
Plenty of things at my current job have formal mathematical proofs backing it and it's helpful when justification is explained like that.
Invariants in networking architecture i need to carefully manage etc.
Depending on the culture some of this stuff is also needed once you get into politics land and need to present your ideas because you know it's better, no? Ig at a large company with too many business oriented minded people this line of work would fall flat
This is my problem with design documents. If your stakeholders already have enough trust that they ask you to go build it without writing a doc, then what value does writing a design doc have.
Many will answer that it helps them think. But why do we need a formal process to think? Thinking is a valuable skill that should be practiced all the time.
I have both read and written several design docs containing informal correctness proofs of nontrivial concurrent/ distributed protocols, so not sure where your dismissive attitude comes from. Not everyone’s environment or experience is exactly like yours.
Compressing your text can not be stressed enough. It makes you think „what do I like to say here“ and that is what most text I have read are missing. In my bussines there is a software called DOORS for req. writing and it’s the death of each document. Like ai slop
I'm writing this with a background of having studied and done a PhD. in software architecture in the early 2000s.
Simply put, good software documentation matters but has the annoying habit of getting out of sync with your software the second you lift your fingers from the keyboard. So, moderate the amount of time you spend on writing especially up-front documentation, like design documents, because they'll have a short shelf life and an even smaller audience. Worst case it's just you. And that's actually fine.
Use them to structure your thoughts. Shoot some versions back and forth with your colleagues to build consensus. And then archive them.
Back when I was doing my PhD. it was peak UML hype. I was interviewing people with important sounding job titles (e.g. Lead Architect) and they'd be in a private office with a prominently displayed Rational Rose box on the shelves. They'd be spending lots of time making diagrams. This job does not really exist any more.
A few years later I decided to practice instead of preach and became a software developer. Now it's a few decades later and I don't do a lot of diagrams. But I do quick Markdown documents or inline documentation. The closer to the source code, the better. I'm actually pretty good about this stuff. And it's stupidly easy to generate this stuff as well these days. Which you should do. Because it really helps others and the future you (come back in four months and you'll find that your short term memory has blanked out everything you used to know about the code).
Why no diagrams? Very simple, they are either too simplistic/trivial or way too convoluted (won't fit on a single screen/slide/document page). Anything in between is quite pointless and tedious to produce. It won't communicate anything of real value that cannot be expressed in a few quick lines of text. Which is much easier to produce. The diagram is what you whip out if you need to put some lipstick on the pig that is your design for marketing purposes. "We have stuff! Look pretty diagram! next slide...".
The other reason is that as soon as you sit down to implement the design, you'll typically refine it on the fly by deviating from it. So, it rapidly goes out of date and updating it is just not a thing that ever happens.
Don't take my word for it. There are millions of projects on Github of just about all sizes. Including quite a few that implement UML editors and IDEs even. Try finding their design documents. You will come up very very short. The larger the project, the less likely it is to have up to date design documentation. You'll find plenty of other documentation and maybe even a wiki of some sorts. But design documentation is not something that is more than an afterthought in the overwhelmingly vast majority of open source and commercial projects (judging from the ones I've been on).
I like to start my design documents with a solution section (sometimes including time breakdowns) - it's a good way to get non-technical audiences up to speed on what will happen, and allows the technical audience to frame their thoughts on the rest of the document.
They usually follow the structure:
1. Solution
2. Context (problem space)
3. Alternatives + Details
4. Logic behind the decision for the solution (reiterating drawbacks)
5. Time/task breakdown (if applicable)
6. Closing remarks
7. Notes (usually only useful for technical audiences engaged in the implementation)
The structure I prefer for a technical design document is like a three-layer onion.The first layer is the problem statement, goals, non-goals, and requirements, both functional and non-functional. The next layer is the functional specification, which describes precisely how the system will work from an external perspective. The third and final layer is the technical specification, which describes the internals.
Each section should follow from the previous. The design doc should justify to the reader (and author) that the problem is understood, the requirements are necessary and sufficient, the functional spec meets the requirements, and the technical spec implements the functionality and non-functional requirements.
As a corollary, if one section has a fatal flaw, there is no need to read on. If the problem is misunderstood, then the functional spec is likely wrong. If the functional spec doesn't meet the requirements, then the implementation is moot.
The issue I see very frequently is technical design documents that provide only the final section—a simple description of the system that will be built. As a design reviewer, there is limited feedback I can provide on such a design. Sure, it's a system, but will it solve the problem? Does the team even agree on the problem to be solved?
This +
Layer one also explicitly identifies stakeholders, and describes the current (AS-IS) situation with annonated screenshots so everyone quickly sees what we are talking about.
Layer two also lists alternative solutions considered and why not chosen.
Layer three is developers making a few notes on chosen tech design, most important is the choice reasoning here.
In all layers, add and use references. Less is more, a picture beats a wall of text.
Yes, agree with all of that. I don't think every design doc needs every possible section, but if readers would benefit from the background or the an enumeration of stakeholders, that belongs up front, before the design.
To add a little more color, each section also has a branch of possibilities. Given a problem, there are many possible functional specs that could solve it. Given a functional spec, there are many possible implementations. The act of choosing from among these possibilities is designing and the design doc should lay out the choices made (and sometimes the choices not made) and why.
Maybe also a section containing a reference implementation.
Or a formal proof, e.g. when discussing secure protocols.
Yes! Non-goals are SO important.
In IT, it's all virtual, so in theory anything is possible. Setting hard limits is necessary, or else the solution space is overwhelming, and the second system effect can kill your project (even in the first system!)
In mechanical or electrical engineering, some potential goals are blatantly physically or economically impossible and do not need to be mentioned as non-goals.
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...
> Replace adjectives with data
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.
If I get one more resume from a “seasoned professional” who has “decreased X by N%” I am going to close hiring, quit tech, and go be a hermit.
N.B. I received such a resume while typing this comment and am absconding to Outer Mongolia as I type
What do you want to see, then? Colorful prose?
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.
I've only been a hiring manager once, and it was for a junior-level position so take that into account.
When I read resumes, accomplishments meant next to nothing to me. I was looking for capabilities.
Your EC2 example is probably an exception to what I'm about to say because EC2 is very well known and you can quantify the difference you made in real dollars. But, 99% of the time I have no frame of reference and therefore no way to evaluate claimed accomplishments on a resume.
Oh, you managed accounts totaling $24MM in accrued receivables annually? Sounds impressive, but what if every one of your peers were managing $30–40MM and you were well known to be a slacker? Etc.
It's much more useful to me to know what classes of problem you can solve and which tools / techniques / technologies you're proficient with toward solving them. Descriptive statistics do very little for me.
> and you were well known to be a slacker? > what classes of problem
If people are going to lie on their resume there isn't a whole lot of anything you can do to fix that at the resume evaluation level. So many resumes have 100x skills where they say they know some language because they happen to walk by a room where someone might have been looking at the wikipedia page describing someone who might have used the language once accidentally.
If you can't relate the impact / accomplishment of the candidate for your job to your company,then that just speaks to a low quality resume. It should be obvious to any reviewer why what you did is relevant to their interest.
The reason why impact matters is that in some sense it should be theoretically reproducible. "Saved 100s of engineering hours by fixing some nonsense" which if true should speak to someone who can ostensibly save time while also understand the meaning of their work.
> It's much more useful to me to know what classes of problem you can solve
There is somewhat less opportunity to bullshit on what problems you have solved than on what problems you can solve.
Not sure about the author, but having a few hundreds interviews under my belt (as the interviewer) some of those statements are incomplete.
Your example is complete, but if I see statements like: "decreased latency by 5%" I will ask you if are we talking about median or long tail latency. Another example would be "developed a ML model that increased revenue by X%". Here it is missing how the population is affected. If you say overall then I will ask you things like: "For which slice of the population did you see the biggest improvement with the new model? Any regression?" or "Did you run any control group".
While I might or might not care about the technicalities of your answer the important thing is that if you can't convince me that you know what you are talking about then it is as parent said, bullshit and I will stop likely paying attention to you and mind my business as I will suggest a no-hire.
If, instead, it looks like you really did those things you mentioned it is a nice ice breaker and genuine candidates seem to perform well when they get the tension out of the way by answering something they know.
PS: If I were to interview you I would ask "How" because as I mentioned it is a complete statement in my mind :)
You want all that on a resume?
No, but hints work. Like the latency one adding "on p99" makes me think it is a specification that adds a lot with just 2 words and the credibility weight it adds is huge (IMHO).
That's a good example for a success. I've seen resumes from Junior devs with <2 years experience, where every line item was a business goal met, and almost nothing on their technical skills they've gotten. Been a hiring manager 10+ years, and it's a trend I've seen more recently.
that formula is preached non-stop on reddit /csmajors /cscareers ect .
If you try to impress a technical interviewer then they will be more interested in the smart idea you had and how you implemented it rather than how much money it made.
It's perfectly fine. The important part is that you can explain during the interview what you did to achieve that impact and demonstrate the skills. A lot of BS ends there. I never threw out a CV because it contained too many numbers or it was too precise. Quite the opposite. I flag CVs that are too vague and use big words without facts often repeatedly but do not provide much information.
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.)
I've read so many resumes over the last few years that I'm just completely overwhelmed by the practice. In fact I now judge resumes unfavorably if they use it more than very sparely.
The best resumes I read (and the strongest candidates) were ones which were very confident in their skills and experience. They showed a bit of personality (as much as you can).
I do feel bad for junior developers. I'm at the point where I won't consider a job unless it came through my professional network. I did a bit of job hunting during some downtime after my last gig just to be diligent while my current was being lined up and it is utterly depressing. LinkedIn and co's "one click apply" has to be the worst thing to happen to the industry for remote workers.
Back in "my day" you'd tailor your resume to the company you applied to in an effort to highlight relevant experience, and that was a minimum- most also included a cover letter... Not fire off three dozen applications a day hoping to hear back from one after a month or three.
Got any extra room in your yurt?
I often read “decreased X by N%” as a slight lie: they don't tell how precise N% was measured and how they can know that all of N% came from their work and not other circumstances.
So my impression is that they work sloppily and oriented more towards office politics than good engineers.
Presenting such numbers to motivate management is a frequent advice on the Soft Skills Engineering podcast [0]. I agree that their (the numbers’) meaningfulness is often doubtful.
[0] https://softskills.audio/
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.
I prefer "more time, shorter letter"
"T ∝ 1/L"
More like ΔL ∝ log(T).
> The goal of a design document is to convince the reader the design is optimal given the situation.
This is a nitpick, but I don't think the goal of a design is to be optimal so much as sufficient.
Software systems design, like any design, is about coping with constraints and tradeoffs. The design doc should clearly lay out these out and present an approach that meets the requirements and constraints with acceptable tradeoffs. Where multiple reasonable alternatives exist, they should be make explicit along with a justification for why one option was chosen over the others.
Will it be perfect? Probably not, unless it is an easy problem or you over-designed. And even if it's a good design, it can hit unforeseen issues during implementation. The goal of design is not to eliminate all possibility of such issues but to mitigate risks and communicate to the stakeholders what we're building and why we're building it that way.
Isn’t “making acceptable tradeoffs” (optimization) while “meeting requirements & constraints” (under constraints) simply optimization under constraints? I fail to see how this is about sufficient _but not optimal_ solutions.
The dictionary defintion of optimal is just 'best'; the connotation that 'optimal' means not perfect, but satisfying multiple constraint, is engineering jargon. In fact, with 'optimal', people will often mean 'Pareto optimal' (a design where there is no change that would improve the solution on all dimensions/constraints).
Pareto optimality also implies that multiple designs may exist in a 'draw', where design 1 is better on dimension A, but worse on dimension B, and design 2 flips those. These designs are on a pareto front. Making the trade-offs explicit helps readers of the design document who come along later to choose a different trade-off when it later turns out that the relative importance of the dimensions involved changed.
I generally read "optimal" to mean "optimal according to some objective function". In the case of a technical design, the objective is not something you can readily formalize, because there are so many considerations.
For example, suppose you are designing a network service to meet some use case. Yes, it needs to meet the use case, but there are other things you care about like simplicity of the code, latency, cost to operate the service, and others.
For any design you propose, there might exist an alternate design that is strictly better by some criteria-maybe it works exactly the same but has much better latency characteristics. If an oracle gave you this design, you might agree it was more optimal and choose to implement it, but I don't think it means you failed if you come up with a (sub-optimal) design that solves the problem within the constraint.
Compromise is the term synonymous with "making acceptable tradeoffs”, not optimisation.
It's also not intended to be frozen in place and some allowance should be made for refinement with out scope breaking (fine but falls under change control) -- the level of detail here is important so known unknowns are surfaced not solved. High Level Designs and Low Level Designs are different documents for a reason allowing for a sufficient approach to be optimized during the transition.
"Optimal" in this context includes time, effort and cost. So the design isn't perfect irrespective of these things, but it is optimal in terms of balancing the effectiveness of the solution with the effort put in.
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.
Here’s a link to Harmel-Laws’post if anyone's interested: https://martinfowler.com/articles/scaling-architecture-conve...
I'm going to have to read that MF.com link fully and properly but I can't help but notice this:
"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 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.
Then do Security, Privacy, Compliance, and the review committees of all affected orgs become blocking reviewers on any PR that touches an ADR? Are these PRs getting merged in less than 90 days?
Fair point about process bloat. Just to clarify: I'm not an ADR expert nor do I personally know Harmel-Law. Just deriving insights from his blog post that I linked to earlier because I thought it was interesting.
But, I think you might be picturing ADRs as heavier than they need to be. Most changes seem like routine updates ("We decided Postgres" → "We're migrating to Aurora") that go through normal code review. The big architectural shifts that would trigger Security/Compliance review probably should anyway, ADR or not.
The key insight is that ADRs document decisions, they don't create them. If a change is big enough to need committee review, it likely needs that scrutiny regardless of whether there's documentation.
The alternative, undocumented drift, often creates much longer delays when people rediscover decisions during incidents. Curious to hear from folks who've actually implemented this at scale, though.
>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.
In my experience there is always more work to be done than there is time. That means people have to start prioritizing things, managers breathing down necks over specific things is a priority signal, just like meetings. Reading something doesn't give you much actual production output to show for, so it just doesn't get prioritized.
Then you should schedule two meetings: one in a reading room, at any time that fits each individual calendar, and then later the real one in a meeting room with everyone's involved, at the same time.
We all know the costs of context switching. Why would you unnecessarily introduce two new context switches? Is it because you don't like being told when to read?
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.
They just do not allocate time to read documents for engineers.
Isn't that how corporate work is usually done? We call the room an office and the babysitter a manager or lead.
> 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.
This is practically the point of meetings. Meetings exist as a forcing function to achieve communication that likely could have happened asynchronously but for some reason didn't.
I disagree. I think companies that have meetings like this have an immature meeting culture.
Meetings are for low-latency collaboration, not information transfer.
For example, reading a design doc is obviously more efficient asynchronously because everyone has different reading speeds and doesn't need everyone else in the room while they read.
Arguing about tradeoffs in a design doc is usually more efficient in a meeting than an email because the low latency communication and additional signals from live communication make the discussion more efficient. For example, if the design doc says we should do X but you think it should do Y, in an email I maybe have to enumerate all the advantages and disadvantages, but in a meeting, maybe you're convinced after seeing just 20% of my rationale.
> For example, if the design doc says we should do X but you think it should do Y, in an email I maybe have to enumerate all the advantages and disadvantages, but in a meeting, maybe you're convinced after seeing just 20% of my rationale.
This is organizationally inefficient. You should write these reasons down in the design document so that you do not need to rely on both of us still being employed 5 years from now to explain to someone who is evaluating the state of the system on why the decision was made. A design document must include justification, not just the final decision, -- that's obvious from the code.
What you're describing as "immature meeting culture" I would instead describe as "mature documentation culture". Different companies work differently of course, and if you're absolutely optimizing for latency and have relatively small groups of stakeholders, meetings are super efficient since you can make all decisions now. But if you're optimizing for throughput and have larger groups of stakeholders, more asynchronous (or entirely asynchronous), document/slack/email driven approaches.
I think the amazon approach is weird and somewhat childish, but I stand by "meeting is only necessary if the stakeholders haven't approved your design offline/async". For such meetings you can use the amazon approach, or you can assume folks have already reviewed and left open comments, and only address outstanding comments during the meeting.
I agree you should document the decisions and discussions around them. I never said you shouldn't, just that the discussion shouldn't be entirely written. But you can discuss live and summarize the discussion in the doc after.
Relatedly, I don't think full discussions about the design doc should live forever in the design doc. When I was at Google, I hated reading design docs where every line had a convoluted, 20-message comment thread attached to it in the margins. When I owned a doc, I'd drive those comment threads to a resolution, write up a concise summary of the debate in the appendix, then resolve the thread.
> Relatedly, I don't think full discussions about the design doc should live forever in the design doc. When I was at Google, I hated reading design docs where every line had a convoluted, 20-message comment thread attached to it in the margins. When I owned a doc, I'd drive those comment threads to a resolution, write up a concise summary of the debate in the appendix, then resolve the thread.
Yes exactly, you don't need the entire back-and-forth, but the relevant information should be written down somewhere.
> Meetings are for low-latency collaboration, not information transfer.
Ok, but without a doc, collaboration in a meeting can become inefficient in many ways. Folks can talk past each other, bouncing between unclear options and losing clarity on what they are even debating. Only one person can talk at a time, so folks are sitting and waiting for their turn, etc.; Strong personalities can dominate and filibuster.
Writing even a bad doc ahead of time can help to make the meeting’s purpose clear. The author can guide the discussion by laying out and labeling big options and decision points.
While reading the doc, everyone can comment in parallel, so you aren’t serializing the conversation for small things or letting some verbose person waste the time.
Reading during the meeting helps folks manage time outside the meeting. It means: you don’t have to prepare for meeting you don’t own. It avoids “random people” assigning you work beyond what they are asking you for in your calendar. For busy managers this is a huge benefit.
I'm arguing for reading the doc ahead of time, identifying topics about the doc to discuss, then coming to the meeting with a specific agenda.
>Ok, but without a doc, collaboration in a meeting can become inefficient in many ways. Folks can talk past each other, bouncing between unclear options and losing clarity on what they are even debating. Only one person can talk at a time, so folks are sitting and waiting for their turn, etc.; Strong personalities can dominate and filibuster.
I don't understand. These are just problems with meetings in general no matter what you do in advance. What are you arguing for?
>While reading the doc, everyone can comment in parallel, so you aren’t serializing the conversation for small things or letting some verbose person waste the time.
>Reading during the meeting helps folks manage time outside the meeting. It means: you don’t have to prepare for meeting you don’t own. It avoids “random people” assigning you work beyond what they are asking you for in your calendar. For busy managers this is a huge benefit.
I don't understand how this can be possible. It means that letting someone else manage your time is more efficient than managing your own time.
If I need 5 minutes to read a document, how is it helpful for someone to force me to sit for 10 minutes to read it at a specific time? It's obviously more efficient for me to read it in the block that I choose and not waste the extra 5 minutes.
The Amazon way sounds like how you'd manage time for a child, where you can't trust them to manage their time, so you have to schedule time blocks for coloring, recess, and eating lunch.
> I don't understand. These are just problems with meetings in general no matter what you do in advance. What are you arguing for?
That by simply requiring a doc, you have forced the person who called the meeting to think about what they want to achieve, and to prepare their thoughts ahead of time. This makes the agenda clear to everyone and helps to guide the discussion.
> It means that letting someone else manage your time is more efficient than managing your own time.
If we are reading the doc together in the meeting, I only need to accept/decline the meeting and I am good.
If I am expected to pre-read, I have to actively do something to schedule that pre-read time. And the doc has to be ready whenever I decide to read it. Multiply that by 10+ meetings a week for a busy manager, and you have a lot of mundane scheduling work to keep straight.
> If I need 5 minutes to read a document, how is it helpful for someone to force me to sit for 10 minutes to read it at a specific time?
I’ve not found that to be a problem in practice. I can use extra time to think and prioritize my feedback, or catch up on Slack, etc.
If your solution to a problem involves changing human nature, you're on the wrong track.
I've been in companies that do this. I like it more than alternatives.
The default for most meetings everywhere I've seen is to present information during the meeting, verbally or in powerpoint. For example, standups often devolve to people sharing their updates. This is much worse than having people write down updates and taking a few minutes to read them at the beginning.
Also note that these documents usually take about 5 minutes to read, even for slow readers. Meetings with much longer documents are pretty rare in my experience - feedback on long documents is usually done separately.
It would theoretically be better for people to read the documents ahead of time. But the benefit is pretty small IMO, and the cost is large – it fails if even a single person hasn't read the document.
I worked at a company where we copied this from Amazon for a specific type of meeting (bi-weekly review). But we also had the other "normal" type of meeting.
People never read the documents before the meeting in those "normal" meetings.
The challenge with your suggestion is that people will half-ass the doc reading before the meeting - we tried doing this for the "normal" meetings. It was obvious the people skimmed the doc before the meeting. You're also now relying on the manager (if there even IS one for everyone in the meeting!) to care about this.
So, in practice, giving people dedicated 10 minutes at the start of the meeting works far better.
Besides, in most "normal" meetings, the main presenter often ends up discussing background / context for 10 minutes interspersed throughout the meeting anyway. In the "pre-read" meetings, you're just compress that to the first 10 minutes while increasing the amount of information transferred.
> 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.
People don’t read ahead of meetings, and that results in wasting time discussing things already covered by docs.
> They could easily do the same thing ahead of the meeting, and you'd have much shorter meetings.
There's no difference in the amount of time spent whether it's read in or out of the meeting. At least spending the time in the meeting to read it, people are more focused on the topic at hand and the time will be better spent. Besides, I'd bet the fraction of those docs that are ready sufficiently ahead of the meeting are in the single digits.
>There's no difference in the amount of time spent whether it's read in or out of the meeting.
I address this point directly in the comment you're responding to.
They could easily do the same thing ahead of the meeting, and you'd have much shorter meetings.
To highlight two ways to go about this, we can assign homework, or assign, for lack of a better word, meetingwork. We don't always know how much free time our colleagues have outside of the time we've scheduled for a meeting. At least by enforcing meetingwork org-wide, it is ensured that everyone has at least some time to read the docs and they're fresh in their mind, even on short notice.
You're right about "reading speed", but I think the common alternatives are no one knows how prepared anyone is vs a few people might not be fully prepared.
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.
In addition to the reasons already listed (slowest reader etc) it's also good, at leasdt for some, to let new information sink in before discussing it.
I suspect these are not real issues. Most people smart enough to be an engineer read fast enough to finish 6 pages in 15 minutes(and your doc is bad if they can't), and discussing it fresh is probably better since you forget less.
you squander sooo much more time whenever people are not on the same page, or if people are worried you didn’t cover their corner case.
In my experience if it doesn't happen in a meeting it doesn't happen.
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 often come across tips/pointers/exhortations about how to write good design documents. I generally agree that it's an important step: not just for clarifying your own thinking, but also for communicating effectively with others.
However, these types of posts often lack are concrete examples of what a good design document actually looks like. I understand that many of these documents are proprietary and intended for internal use. Still, are there any examples of well-written design documents available publicly that learners can study to get a clearer idea of what one should look like?
> However, these types of posts often lack are concrete examples of what a good design document actually looks like
The entire post is an application of his document designing philosophy. It became obvious with his first header being "Goal" and him mentioning to set a goal early on.
This should grow from within yourself. Read a lot of design docs and blog posts and articles and books. Which ones did you like? Which were confusing? And why was that? Was it the language complexity? Length of explanations? Diagrams? Too much / too little reasoning? Did you feel that the writer did a good job of picking you up were you were and brining it to a new state which now was enriched with their idea?
Constantly ask youself whether you liked a particular piece of writing and that will over time shape your understanding of what's good and what's not. Note that that's not entirely objectively quantifiable and people will have different tastes. That's also why it's hard to have a "good examples" archive because, just like with code, that would immediately people to start debating. But there is a certain core of properties most people can agree on.
Somewhere in some comment antirez said he writes design documents for his projects before he writes a single line of code. You can browse his GitHub projects or google “antirez design documents” or “antirez specification”.
https://github.com/antirez
Yes this is also a question that comes to my mind. Where are the design docs from the past 50 years of software development. There must be something concrete for people to study and learn from.
I've been doing this stuff for 40 years and spent the first 20 or so looking for design documents (having been asked to write many). Eventually I realized there are none. At least almost none, and very few that existed prior to the related software being written.
The AWS Lambda PR/FAQ was released late last year - worth a read
https://www.allthingsdistributed.com/2024/11/aws-lambda-turn...
Also not a design document?
The problem with design documents is that they require maintenance which takes more effort than it solves problems.
What kind of maintenance do you mean?
A design can evolve over time, but a design document's objective is to document what was going to be built at that time. If something changes, make a new design document. (Similar to blog posts or news articles, they also don't evolve over the years. You write a new one.)
It sounds like what you mean is system documentation, a handbook of sorts, and that's what needs maintenance. But that's different from a design doc.
> What kind of maintenance do you mean?
> If something changes, make a new design document.
This one.
Without fail, people who say this really mean "I am unable or unwilling to put in the hard work at the design stage to resolve uncertainty and will instead push these problems downstream to the development process where hopefully no-one will remember I'm responsible for the ensuing mess".
Yes, that's correct. In other words, my cost-benefit analysis concluded that shipping fast and iterating later is a much better strategy than spending countless manhours on plans and meetings in order to provide a product that is perfect from technical perspective but misses both the timing and market needs. I don't understand this fetishation of "perfect code" when experience shows again and again that for most use cases, the correct approach is to ship fast and fix later. We're not sending a spaceship to Mars, we're making an AI-based social media app, either we ship this week or next week facebook will launch its own version which will make our product completely irrelevant and being first to release a feature is the only way to capture a statically significant part of the market. As long as the most common use case works we're grand, if 80% of the app doesn't work that's fine because 80% of the users only use the main 20% of the app, and the focus is on making sure that this works correctly.
> I don't understand this fetishation of "perfect code" when experience shows again and again that for most use cases, the correct approach is to ship fast and fix later.
You're conflating two separate issues, because design documents help you ship faster and fix later. They do this by making you think about what you're building, thereby allowing you and downstream consumers of the plan to focus on a smaller and more valuable set of goals.
Your approach is the opposite - building by gut feel and ignoring the available data. That's leads to wasted effort and elongated development cycles.
> my cost-benefit analysis
You don't plan, so you don't know your costs or benefits.
One process that can work:
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.
I feel like the process of editing my own stuff is at least as important as getting it down. That's when I go back through it and realize all the conclusions I leapt to, things I didn't thoroughly consider, and other flaws. I think people really undervalue writing as a focus tool. But maybe that's just me, YMMV.
I think the same thing about a lot of code, too. Sometimes you really are just hammering out boilerplate. But a lot of times even writing test code is a great opportunity to realize the main code could be improved. But the LLM probably won't tell you that.
Expand, condense, compress, expand, compress.
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 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.
Nothing wrong with sticking a summary up top, and then laying out the arguments below.
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!
Hadn't seen it that way - PR/FAQ - Press Release / Frequently Asked Questions https://productstrategy.co/working-backwards-the-amazon-prfa...
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.
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...
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.
This article is written front-loaded with vague ideologies, basic mostly-intuitive foundational concepts followed by a random mishmash of general tips. I was hoping for a more applied and structured tour with effective examples that work for common classes of problems.
A reasonable starting place: The best design document conveys the critical aspects, requirements, and relevant information in a way the audience will understand and be able to further reason about.
p.s. Sorry for the complaint, I was a bit disappointed because this is potentially a really interesting subject! Why does cargo-cult content get such good traction so consistently? Cargo-cult driven design leads to some odd outcomes IME. Sigh
It's worth noting the author led the implementation of the file system at the bottom of S3.
Logistically speaking, is there a good hosting service for design docs but have google docs-like functionality to be able to comment and share feedback? I increasingly use tools like cursor to iterate on design docs that are in markdown format and currently I move things over to google docs manually and when there is feedback, I need to go back to cursor which creates a slow and weird loop. Have people identified better structures/processes for this?
https://hackmd.io might fit the bill. I use it for some open source projects I work on, but don't really touch the advanced features.
We use Notion and most people seem to like it. I find it quite quirky but it does a good job of allowing comments and feedback that can then be marked as "resolved".
I'd probably prefer a pure markdown solution but I'm not aware of one.
I used the following sources to create an RFC template (and promote the document culture across the engineering documentation):
- https://www.industrialempathy.com/posts/design-docs-at-googl...
- https://github.com/rust-lang/rfcs
- https://github.com/kubernetes/enhancements/blob/master/keps/...
- https://blog.pragmaticengineer.com/rfcs-and-design-docs/
Hint: tailor the process and template structure based on your org size/maturity and needs. Don’t try to blindly mimic/imitate.
I'm broadly in favor of RFCs but they need to be dictated from top-down. That's easier said than done.
Most RFC committee debates ime devolve into firing squads in which the presenter needs to answer every question with pin-point accuracy and perfect context from the asker. Otherwise, they look unprepared and the RFC is negated.
This is allowed to happen because everybody is a theoretical co-equal in the process. Thus, everybody wants to have their say. You'd hope people would read ahead of time but there's always somebody who doesn't yet feels entitled to ask pre-emptive questions. It makes for very combative discussions.
The exception is when a double-skip manager stops that from happening and lets the presenter "make their case" and walk through the whole RFC.
Re: https://www.industrialempathy.com/posts/design-docs-at-googl...
> ... sketching out that API is usually a good idea. In most cases, however, one should withstand the temptation to copy-paste formal interface or data definitions into the doc as these are often verbose, contain unnecessary detail and quickly get out of date.
Using R Markdown (or any Turing Complete documentation system), it's possible to introduce demarcations that allow the source code snippets to be the literal source of truth:
Use a GPT to implement a parser for snippets in a few minutes. Then invoke the function from the living document for given a source file, such as: The documentation now cannot ever go stale with respect to the source code. If the comments are too verbose, simplify and capture implementation details elsewhere (e.g., as inline comments).In one system I helped develop, we were asked to document what messages of a standard protocol were supported. The only place this knowledge exists is in a map in the code base. So instead of copy/pasting that knowledge, we have:
And something like: This snippet is parsed into an R dataframe. Another function converts dataframes into Markdown tables. Changing the map starts a pipeline that rebuilds the documentation, ensuring that the documentation is always correct with respect to the code.If a future developer introduces an unparseable change, or files are moved, or R code breaks, the documentation build pipeline fails and someone must investigate before the change goes onto main.
Shameless self-plug: The R Markdown documentation system we use is my FOSS application, KeenWrite; however, pandoc and knitr are equally capable.
https://keenwrite.com/
> 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.
Is there a collection of good design documents somewhere?
I'm a few decades into my career and can't recall ever seeing any.
I would also love to see some so I can share them with my team.
We’re a very tribal company so standards vary widely, and I’m curious to see what industry gold standard looks like.
Going off on a tangent, but:
> This disappoints the ego-seeking behavior of many engineers. Good engineers often want people to realize how clever they were.
This is probably partly true to a small extent, but for the most part I think it trivialises a larger problem.
I have had this exact problem as an academic publishing papers. My ability to write straightforward easy to follow manuscripts has backfired on me many times, whereby explaining the steps in a clear, intuitive order has led reviewers to state that the findings were non-novel since they were a clear intuitive series of logical steps. My (sad) experience has taught me that if you make the reader 'work' a tiny bit towards developing the intuition themselves, and appreciate how this specific sequence of steps wasn't necessarily trivially obvious before announcing it on paper, then they will appreciate the novelty and the thinking that went behind it a lot more.
Obviously I don't necessarily think the mass of obfuscated papers out there are academics intentionally obfuscating to prevent rejection and raise appreciation in their readers (it's more likely to be a lack of skill or interest in investing the effort to write more clearly). But (despite it's frequent abuse as a phrase) leaving _some_ things as "an exercise to the reader" turns out to not always be the 'lazy' or 'ignorant' thing to do.
Now, of course, design documents may not necessarily have the same goals or gatekeepers as academic papers do, but I think attributing leaving some steps up to the reader to be entirely about engineering ego-seeking behaviour is a bit misguided. If your goal is to make someone understand and appreciate something, then there is such a thing as "explaining it too much" (and thus robbing them of the experience of developing their own, and far more useful, insight).
And this is doubly true in teaching contexts (arguably not the usual purpose of a design document, but ...).
The author makes the following assertion:
I find this _extremely_ surprising???What do you find surprising---the fact that it doesn't come out red, or the fact that people are confused by this behaviour?
I should write a lot more, but the two paths I see are: B.O.O. and Good Strategy/Bad Strategy.
B.O.O.: Background, Objective, Overview. Basically, a history lesson for how you got here, an objective for what you want to fix/change, and an overview of how you'll implement that change.
Good Strategy/Bad Strategy: An amazing book, but the organization is similar to boo. Problem Diagnosis, Guidelines/Assumptions/Requirements, and Actions.
I find BOO is better for targeted design documents in a google-like culture where you should write up a design document for almost any architecture change. The Good Strategy/Bad Strategy method scales pretty amazingly up to almost anything, but you need to be a much more experienced author to get things to fit it.
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.
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...
I think the article would be much more useful if the author applied the principles to design a good design document.
i'm really surprised drawings aren't mentionned.
Engineers have used drawing for millennia and yet software developers seem to be completely unfamiliar with them. A good drawing will help people visualize the problem in an instant, and let people talk about the different options much more easily.
The opposite of this is a culture where "we just work it out in slack."
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.
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 follow you.
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.
This looks like excellent advice and I'm going to have my apprentices read it and use it to critique some design docs we use at $WORK.
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.
Dilbert was just a normal person with average intelligence. His intelligence was magnified by ppl around him.
Perfect for dragging into my context window :). Thanks!
I wish i was allowed by my employer /organization/work culture to write DD in a format this reasonable.
> 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.
Oh, I interpreted design documents as general things - documentation included.
Plenty of things at my current job have formal mathematical proofs backing it and it's helpful when justification is explained like that.
Invariants in networking architecture i need to carefully manage etc.
Depending on the culture some of this stuff is also needed once you get into politics land and need to present your ideas because you know it's better, no? Ig at a large company with too many business oriented minded people this line of work would fall flat
This is my problem with design documents. If your stakeholders already have enough trust that they ask you to go build it without writing a doc, then what value does writing a design doc have.
Many will answer that it helps them think. But why do we need a formal process to think? Thinking is a valuable skill that should be practiced all the time.
Writing for yourself is a good way to think.
Writing is also s good way to document to others that you have thought about the topic/problem/solution.
I have both read and written several design docs containing informal correctness proofs of nontrivial concurrent/ distributed protocols, so not sure where your dismissive attitude comes from. Not everyone’s environment or experience is exactly like yours.
Compressing your text can not be stressed enough. It makes you think „what do I like to say here“ and that is what most text I have read are missing. In my bussines there is a software called DOORS for req. writing and it’s the death of each document. Like ai slop
Yes, and we need more people writing RFCs.
I'm writing this with a background of having studied and done a PhD. in software architecture in the early 2000s.
Simply put, good software documentation matters but has the annoying habit of getting out of sync with your software the second you lift your fingers from the keyboard. So, moderate the amount of time you spend on writing especially up-front documentation, like design documents, because they'll have a short shelf life and an even smaller audience. Worst case it's just you. And that's actually fine.
Use them to structure your thoughts. Shoot some versions back and forth with your colleagues to build consensus. And then archive them.
Back when I was doing my PhD. it was peak UML hype. I was interviewing people with important sounding job titles (e.g. Lead Architect) and they'd be in a private office with a prominently displayed Rational Rose box on the shelves. They'd be spending lots of time making diagrams. This job does not really exist any more.
A few years later I decided to practice instead of preach and became a software developer. Now it's a few decades later and I don't do a lot of diagrams. But I do quick Markdown documents or inline documentation. The closer to the source code, the better. I'm actually pretty good about this stuff. And it's stupidly easy to generate this stuff as well these days. Which you should do. Because it really helps others and the future you (come back in four months and you'll find that your short term memory has blanked out everything you used to know about the code).
Why no diagrams? Very simple, they are either too simplistic/trivial or way too convoluted (won't fit on a single screen/slide/document page). Anything in between is quite pointless and tedious to produce. It won't communicate anything of real value that cannot be expressed in a few quick lines of text. Which is much easier to produce. The diagram is what you whip out if you need to put some lipstick on the pig that is your design for marketing purposes. "We have stuff! Look pretty diagram! next slide...".
The other reason is that as soon as you sit down to implement the design, you'll typically refine it on the fly by deviating from it. So, it rapidly goes out of date and updating it is just not a thing that ever happens.
Don't take my word for it. There are millions of projects on Github of just about all sizes. Including quite a few that implement UML editors and IDEs even. Try finding their design documents. You will come up very very short. The larger the project, the less likely it is to have up to date design documentation. You'll find plenty of other documentation and maybe even a wiki of some sorts. But design documentation is not something that is more than an afterthought in the overwhelmingly vast majority of open source and commercial projects (judging from the ones I've been on).
I like to start my design documents with a solution section (sometimes including time breakdowns) - it's a good way to get non-technical audiences up to speed on what will happen, and allows the technical audience to frame their thoughts on the rest of the document.
They usually follow the structure:
1. Solution
2. Context (problem space)
3. Alternatives + Details
4. Logic behind the decision for the solution (reiterating drawbacks)
5. Time/task breakdown (if applicable)
6. Closing remarks
7. Notes (usually only useful for technical audiences engaged in the implementation)