Writing a good design document
grantslatton.com
grantslatton.com
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?
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.
Or a formal proof, e.g. when discussing secure protocols.
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.
That still requires the rest of your process, and perhaps even places more emphasis on those documents. The infrastructure implementation needs to follow from the high-level technical design which needs to follow from the functional specification. Because as you say, the implementation needs to be reviewed against a specification. What are you reviewing if the spec is incomplete?
Design documents are so essential that even after mumble years in the industry, I am amazed when people, including putative "Product Managers" push back on the idea. As Leslie Lamport noted, "Writing is nature's way of telling us how sloppy our thinking is."
For those wanting to learn how to improve the quality of their technical writing, see Write Like an Amazonian: https://medium.com/@apappascs/write-like-an-amazonian-14-tip...
I think this idea got so pervasive all throughout tech that all the resumes that i now get are filled with so many numbers that i don't even know what to make of them.
The recruiters will do and react to what the hiring managers ask for. When one too many candidates slip thru who bullshit, or there is weak signal that such and such method of candidate selection seems to result in marginally stronger candidates, then everyone rushes to do that thing and it eventually becomes sludge. Leetcode interviews are a classic example.
We (individuals) get poor candidates because we (industry) encourage and reward poor recruitment practices. Time for us all to look in the mirror, honestly.
I've seen 300k salary hiring managers punching down on a recruiter making 60k who doesnt know her C# from her C++. That sort of behavior says more about the flaws of the hiring manager than the recruiter. If you never talk to the recruiter but once a year when you have budget to hire someone, never take the time to educate them on your business, well then you're going to get crappy candidates.
in response, for HR it is much easier to filter out CV if it lacks style, not substance. Therefore they look at bullet points like "Done X by Y%".
The proper way should be to limit the intake funnel: accept only a few applications per job, so that they can be screened properly by HRs by calling them, and talking to them and properly screening (old school style), instead of tossing their resume to the bin after 15 sec quick review
N.B. I received such a resume while typing this comment and am absconding to Outer Mongolia as I type
I and a few others really did save my company 10 million dollars one year. It was in EC2 spend for a hadoop cluster. I can tell you how we did it and who did what. Yes it was actual dollars we would have otherwise paid to AWS, it is not funny money calculated by looking at sticker rates and ignoring our discounts (which were large).
I'm proud of this and it was one of my largest impacts at the company. What would you have me put on my resume? "Decreased EC2 spend by a whole bunch!"? "Reduced EC2 spend"?
I don't get where this hatred of numbers on resumes is coming from. Is much of it probably bullshit? Yeah, just like most resumes. But I expect you to sort through it the same way you do the rest of the resume. Ask them about it. I can tell you the whole story of mine. I'd expect others can do the same. And if they stammer and crack, now you know how exaggerated it was.
So keep doing it if you don't actually care. If you do, maybe try to think of a different way to communicate it that sets you apart.
The 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).
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 :)
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.
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.
There is somewhat less opportunity to bullshit on what problems you have solved than on what problems you can solve.
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?
So my impression is that they work sloppily and oriented more towards office politics than good engineers.
> 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.
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.
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.
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.
Here’s a link to Harmel-Laws’post if anyone's interested: https://martinfowler.com/articles/scaling-architecture-conve...
"That’s it. That’s the Advice Process in its entirety." (speak to everyone involved).
Presumably anyone with the term Managing as a prefix in their job title is expected to glaze over at roughly this point.
Then we get to the meat: "The four supporting Elements". So I try to find out about ADRs:
I follow the first link:
https://www.thoughtworks.com/radar/techniques/lightweight-ar...
and eventually end up with this beauty (big download button at the bottom of the page from above):
https://www.thoughtworks.com/content/dam/thoughtworks/docume...
Would you mind pointing us at an actual definition of ADRs, please?
There Harmel-Law defines ADRs as "lightweight documents, frequently stored in source code repositories alongside the artefacts they describe." He also provides a handy "Elements of an ADR" table. Let me know if you're still having problems finding it.
I do like to wrap up ... eventually! 8)
Btw use Signal if you want secure messaging, full stop.
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.
I've never worked at Amazon, but I've heard this a lot, and it always strikes me as an odd practice. Odder still is that it apparently works and everyone I hear talk about it seems to love it.
You're squandering precious meeting time by having everyone sit and read a document together. They could easily do the same thing ahead of the meeting, and you'd have much shorter meetings.
And doing it synchronously means everyone either sits idle until the slowest reader is ready or not everyone gets to finish in time. And "slowest reader" isn't even just about reading speed. Presumably, some people can understand the document more quickly because they have more context.
In design reviews at Google, it was obvious that the majority of attendees came unprepared and were reading the docs for the first time while their teammates were discussing the doc. I suspect that the reason was that Google just didn't have a strong docs culture, and leads/managers quietly tolerated people coming unprepared (and sometimes, they themselves were unprepared).
I've never seen it done in practice, but I don't think it would be hard to have the best of both worlds where people review docs ahead of the review meeting, but there are strong cultural norms around reading docs ahead of time so the meeting is just for discussion, not just for reading or pretending that you've read.
Amazon’s practice is a reaction to the fact that nobody actually does this. According to the article I read about this years ago, they realized that “creating a strong culture around reading before the meeting” also isn’t possible because many attendees had a meeting before this one, and couldn’t prepare for that meeting because they had a meeting before that, etc.
On paper you could punch a ton of holes in this: Why not reduce the number of meetings people have to attend? Doesn’t the reading reduce the amount of time available in the meeting to actually make decisions? But it would seem that in practice they found that the meetings people were attending did in fact have value, and that even with the reading time a lot of decisions got made.
So this may just be one of those things where you have to look at the results instead of worrying about what could theoretically be done differently. And it sounds like people really like the results and that the benefits of this approach outweigh the drawbacks, at least at Amazon.
But isn't that bizarre? I can't think of anything else where we need engineers to do something by a deadline, and we just resign to the fact that they won't do it unless we sit them in a room and babysit them while they do it.
Pretty much anything, unless you're in the engineer's management chain, or you've given them a direct incentive.
It's always been my experience in bigco that people can ignore almost anything that doesn't come from their management chain up until scheduled meetings get involved. Being uncooperative with meetings (declining invites without alternatives; not attending; not participating) are when escalations and complaints start occurring, and there seems to be a silent consensus that this is the standard - as in, if you complain that someone hasn't answered your emails, the standard response you should expect from anyone, including their manager, is "then schedule a meeting."
So, if you need someone to do something, you schedule a "meeting" to block time on their calendar in which they will pay attention to your thing. That includes anything they need to do to prepare, because anything you don't include in that time block isn't part of the meeting and therefore isn't going to get done.
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.
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.
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.
>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.
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.
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.
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.
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.
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.
People don’t read ahead of meetings, and that results in wasting time discussing things already covered by docs.
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.
I address this point directly in the comment you're responding to.
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.
Step 1. Brain dump into a doc (consider using dictation to get more thoughts down faster)
Step 2. Have an LLM give it structure & progression. You are ordering your thoughts for readability, so you'll probably want to throw it away. You're still refining your thoughts at this stage.
Step 3. Take the LLM output as a starting point, or write an outline from scratch. Flesh it out into a first draft
Step 4. simplify: cut words, swap big words for small words, etc.
Step 5. Repeat step 4.
LLMs bridge the gap from word-vomit to structure. You should be willing to throw away what you get from the LLM.
At least 30% can always be cut. It's amazing how much can be trimmed without losing the intent.
Then somebody comes along and asks about something specific, so you expand.
Finally they use an LLM to compress after their pet idea was satisfied.
It’s crazy really, we’re just on a never ending rollercoaster here.
I 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.
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?
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.
> If something changes, make a new design document.
This one.
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.
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.
https://www.allthingsdistributed.com/2024/11/aws-lambda-turn...
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.
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.
That said, work back from your customer!
A recent project's tech appendix had headers like "Core Technology Philosophy", "Backend Architecture", "Frontend Architecture", "Service Architecture", "Infrastructure and Deployment", "Security Architecture", "Performance Requirements", "Configuration Management", "Backup & Disaster Recovery", "Development Workflow", "Network Architecture", "Resource Management", "Development Principles", and "Scalability Considerations".
The beauty is that by the time you get to the technical appendix, you've already validated what you're building and why it matters. The technical choices then flow naturally from the customer requirements rather than driving them.
I 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...
A example doc would of been really helpful, I'd love to compare the final structure of mine with others.
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
I'd probably prefer a pure markdown solution but I'm not aware of one.
- 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.
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:
// DOCGEN-BEGIN:API_CLASS_NAME
/**
* <description>
*
* @param arg <description>
* @return <description>
*/
uint8_t method( type arg );
// DOCGEN-ENDED:API_CLASS_NAME
`r#
snippets -> parse.snippets( "relative/path/to/ClassName.hpp" );
docs -> parse.api( snippets[[ "API_CLASS_NAME" ]] );
export.api( docs );
`
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:
MessageMap MESSAGE_MAP = {
// DOCGEN-BEGIN:SUPPORTED_MESSAGES
{ MessageType1, create<MessageClassName1>() },
{ MessageType2, create<MessageClassName2>() },
...
// DOCGEN-ENEDED:SUPPORTED_MESSAGES
}
`r#
snippets -> parse.snippets( "relative/path/to/MessageMap.hpp" );
df -> parse.messages( snippets[[ "SUPPORTED_MESSAGES" ]] );
export.table( df );
`
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.
I'm a few decades into my career and can't recall ever seeing any.
We’re a very tribal company so standards vary widely, and I’m curious to see what industry gold standard looks like.
> 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.
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.
Hated this about Amazon; I need to be in a certain state of mind when reading technical prose which is hard to arouse on a whim. Happy to make and submit edits prior to meeting and then discuss. I also much prefer token passing when making modification of the document, rather than simultaneous people marking it up.
I'm usually the only person that ever reads my docs, so I write docs for me.
I also often write design docs during, and sometimes after my projects.
I call it Forensic Design Documentation[0].
[0] https://littlegreenviper.com/miscellany/forensic-design-docu...
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.
I do like discussing things after the fact. I think a "proof" is a good starting point, and if you don't start with at least that, then jumping into a slack conversation to do that foundational work causes problems.
I really like a PR as as the place to put the proof: you can only assume it is true for that moment in code, and it is associated with that. Of course it isn't remotely true as all software has bugs, but at least it can be a concise statement of how you understood it at the time, and that's valuable. The author is noting that you need to get into the mental model of the author, and this is a good place to capture your thinking.
I think READMEs for a repository, in general, are almost always worthless and outdated, like you allude to.
If you can’t write the documentation before you’ve written the code, you don’t understand well enough what you’re building the code for.
It’s one thing to jump into code because it’s fun to write code. But writing code is not designing software, and vice versa.
Same goes for APIs. Writing docs for an API that doesn’t yet exist can help create a much more complete and coherent API.
This is why I’m often trying to help stakeholders understand that the vast majority of software development has very little to do with actually writing code.
Herein also lies a concern I have about AI assisted development. It can be a powerful aid to the design stages, and it can be a powerful aid to writing code, but I’m not sure it enables skipping the design aspects altogether and somehow coming up with a complete, coherent product.
We don't need to veneer technical writing in faux rigour for it to be worthwhile. That's the silly stuff that belongs on LinkedIn.
This kind of psuedo-rigor feels good to nod along to, but it's nonsense.
'We're not writing code, we're programming', 'we're not just programming, we're doing software engineering', and now 'we're not doing software engineering we're doing rigorous proof based mathematics' all of a sudden.
IDK how you write 'Think of a design document like a proof in mathematics.' without feeling at least a little bit silly.
> The goal of a design document is to convince the reader the design is optimal given the situation.
A proposed design may be optimal, or it may not, but the purpose of a design document is not to prove that the proposed design is optimal by any definition.
In a software development setting you're virtually NEVER formally proving anything, nevermind optimality.
You're writing technical fiction based in reality, nothing more. It's not a 'proof' of anything.
You're convincing stakeholders that your proposal can be feasibly built, is viable to run in the ecosystem of the rest of your codebases and infrastructure, and satisfies whatever business requirements that led to someone asking you to create a new $thing the design doc is aiming to propose the technical solution for.
Nothing more IMHO.
If your doc isn't doing those things then it's not effective, if it's giving the illusion of trying to do more than those things then it's just theatre.
The rest of the article is standard good writing advice, but can we not put design docs and PRFAQs on an altar as anything more than technical business fiction to communicate ideas and proposals for scrutiny to stakeholders.
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 is also s good way to document to others that you have thought about the topic/problem/solution.
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
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).
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)