
Design Docs at Google - thesephist
https://www.industrialempathy.com/posts/design-docs-at-google/
======
cameronbrown
Design docs are one of my favourite things about software engineering. If code
is the bricks and mortar, then these docs are the blueprints.

I know this is fairly controversial, but our jobs isn't just to write code.
Navigating organisations and achieving consensus between a lot of
teams/technologies is a huge part of it.

Design docs are a way to get all of that out of the way _before_ writing
thousands of lines of code. The review process nets significantly different
feedback to code reviews too.

~~~
learc83
>If code is the bricks and mortar, then these docs are the blueprints.

That analogy falls apart quickly. Design docs aren’t specific enough to be
analogous to blueprints.

You can give a set of blueprints to 3 different construction firms and get
fundamentally the same building. Try giving design docs to 3 different
development shops and see what happens.

The problem is that the only way to get to that level of specificity is with
code.

Design docs are closer to something a city planner would produce than to
something an architect or civil engineer would, and they should be treated
accordingly.

~~~
nickbauman
This is something that should be taught to folks while they're still in
school. The "blueprint analogy" has baked in the idea that there's a "design
phase" and a "construction phase" and that these are often discreet parties.

Nothing could be more incorrect when it comes to software. In software, _the
design is the code._ The compiler/interpreter are the construction of the
system.

~~~
supahfly_remix
If the design is the code, then what is a bug? There is a separate model,
whether written down or not, of what the code must do. That is the deaign.

~~~
learc83
What happens when there is a flaw in the design? There's another higher level
of design on top of that, with a platonic ideal of the design unknown to
humans at the top? Turtles all the way down.

Each stakeholder has a different "design" in mind, and until you actually get
specific there is no design, there's just a nebulous, incomplete list of
requirements. And if you do try to get specific enough to be reproducible--
you're writing code.

None of this is to say that design docs are worthless, just that they can
never be specific enough to function as the actual reproducible design the way
blueprints would. Thinking of them that way is harmful.

~~~
Kinrany
It's true that they're not reproducible. Are there other noticeable
differences?

~~~
learc83
Reproducibility is just a side effect of lack of specificity, which is the
major difference and the entire point of my critique. Design docs don't tell
you enough to actually build the thing you want to build.

~~~
Kinrany
I mean, are there any practical consequences other than the inability to make
the same thing twice?

~~~
learc83
Assume you hold the view that a design document provides all the information
necessary to construct a piece of software without any further design work.

Construct a software development methodology around that assumption. Now
remove that assumption, and think about the practical consequences for a team
who doesn't realize that the assumption is incorrect until after they have
started implementing a design document.

Imagine what would happen if you hired an architectural firm to draw up some
blueprints for a house, and then midway into the construction of the house it
turns out that the assumptions made in the blueprints are wildly out of sync
with what's possible to build.

It is significantly better for everyone involved if management goes into the
process knowing the limitations of design documents and up front design.

For more concrete example of the practical problems see the history of the
debate between iterative and big design up front methodologies over the last
30 years.

------
staplung
I worked at Google for 4 years. One thing that has always surprised me about
documentation at Google is that they use Google Docs (just like everyone else)
but have never seemed interested in making it less of a terrible tool for the
task. It's relentlessly print oriented, which makes almost no sense these days
(when was the last time you printed out a Google doc?), has no affordances for
dealing with pre-formatted text (e.g. code), has basically no support for
mathematical formulas, etc. In fact its actually evolved to be less suited to
the task of technical documentation since it began given that earlier versions
at least allowed you to define your own paragraph styles. I was hoping that
Google Colab might evolve into a better/more general tool for writing tech
specs but it doesn't seem to be moving in that direction really.

~~~
influx
I feel like Google has given up. The iOS Gmail app is terrible and buggy. The
web app literally has a loading screen now. The GSuite set of products hasn't
advanced much since it was acquired from outside Google. Google Cloud is
getting curb stomped by Amazon and Microsoft. I guess they have Search still,
but it's getting ad filled and tired. Not that I'm going to short GOOG anytime
soon, but come on folks!

~~~
m0zg
One thing people don't get about Google is how it motivates its employees. You
get promoted for _taking credit_ for _launching new stuff_. I deliberately
mention "taking credit", because if you can't take credit for the work you've
done, you're better off not doing anything at all; a prime example of this is
launching a project someone else started but abandoned. Note that you also
don't need to do much work to be able to "take credit" \- it's easier to just
"lead" a project which is already on its way to getting launched by sitting in
meetings with people more senior than you.

You get _nothing_ for improving things that already exist. As a result you get
four different messaging apps, and not a single one that doesn't suck, and a
bunch of stagnating, seemingly abandoned products. The reason is simple:
people who are smart enough to understand the rules of the game move on
immediately after launch to the next big thing.

Having said that, I still prefer GSuite to Office. Microsoft has set the bar
very low indeed.

~~~
pradn
That's a popular perception but it's not totally true. You need to be able to
measure improvements you make, which might make a large category of possible
improvements untenable from a perf point of view. But if you can show
satisfaction scores or latency numbers or action-conpletion metrics or even
just customer comments saying it solved their issue, that's plenty reason to
attempt the change. The system encourages you not to work on things that "feel
good" but instead things that are measurable. There's pros and cons to this as
you can imagine.

That all said, I think the bigger problem is a willingness to put out things
that don't meet a high standard. Ex: the new web GMail launched while slower
than the older one. This was done to get new features out to users faster, but
it doesn't feel that great from a product excellence POV. There's no Steve
Jobs figure telling us the Pixel 4 doesn't look great and as a consequence we
should go back to the drawing board. It's more like there's a set of market
survey results and the phone was made to check those boxes.

~~~
amznthrowaway5
The perception m0zg outlined still seems correct. The system encourages
deceptive reporting of metrics. If you can take credit for improving things
with metrics, while causing far more damage in the process or making no real
contributions, you will still get promoted.

------
ChrisMarshallNY
I'm of a mind to reduce documentation as much as possible, or keep it as vague
as possible.

That's because I came from an environment that insisted on incredibly
detailed, formal, approved-by-everyone-including-the-mens-room-attendant,
documents.

These became "concrete galoshes"[0] that turned what should have been an
agile, iterative project into a waterfall behemoth that cost a mint, took
forever to make, and delivered a result that no one wanted.

I suspect that my current process[1] would not be acceptable for many
organizations, as it basically requires that everyone involved be extremely
experienced, and kept together as a team for years.

I've actually come to realize that "tribal knowledge" is not the boogeyman
that its made out to be; but is a way to get very high-quality, rapid,
adaptive, development done. The main issue is that it does require good,
empathetic management, long-term retention of experienced, capable people, and
an "apprenticeship" model. These are not popular concepts in today's corporate
world (at least, in the US).

[0] [https://medium.com/chrismarshallny/concrete-
galoshes-a5798a5...](https://medium.com/chrismarshallny/concrete-
galoshes-a5798a55af2a)

[1] [https://medium.com/chrismarshallny/forensic-design-
documenta...](https://medium.com/chrismarshallny/forensic-design-
documentation-54541925d30e)

~~~
lhorie
I think something people need to be aware of is that the engineering culture
at places like Google is extremely different than, say, a bank.

Design docs work well for Google because it has decentralized, independent
engineering teams composed mostly of reasonable people, with few or no
mandates from outside their teams. They tend to fail at companies with
underperforming, micro-managing, and/or overreaching teams (e.g. unionized
project managers that have literally nothing to do, bizdev telling developers
what features to implement (down to specifics), QA teams who are incentivized
to find "flaws" ad-infinitum to look busy, etc).

But I see this as a symptom of a fundamental dissonance in goals. Design
documents are used by organizations whose goal is to build/change things. Many
organizations are averse to change, and their processes reflect that, through
overly microscopic documentation, convoluted approval chains, etc.

~~~
ChrisMarshallNY
Yeah, you are correct.

But I have become rather cynical about the motivations of a lot of
organizations, these days.

Everyone seems to be promoting an environment where there's a constant
circulation of relatively inexperienced (not always low-paid, but
inexperienced) developers, staying at companies for short periods of time,
then moving on.

This requires a codified, ingrained structure that needs to be documented and
supported. It applies to modern, "agile" companies, as much as it does to more
traditional, "hidebound" corporations. People that come in need to be
onboarded quickly, squeezed for every ounce of productivity possible, then let
go, when they are no longer useful.

This is supported by the employees, as much as by the managers. The salaries
can be quite high; especially for people that are quick to adapt and come up
to speed.

But there is absolutely _no substitute_ for an experienced, cohesive team that
has developed a shared vocabulary and focus.

I was fortunate to be a member of such a team. The person with the least
seniority on the team had a decade. Everyone had over 30 years' experience in
software development, and we got some fairly intense stuff done. Sadly, we
were still subject to the kind of structure I mentioned above, and a lot of
our product ended up being housed in substandard wrappers (we did "engine"
code).

------
jeffbee
A fun activity if you’re a Googler is to go read ancient design docs, like the
original pitch for bigtable. They are pretty short for the most part, and they
were written by the legends. These are the Federalist Papers of your company,
they give real context to how the company arrived here. In particular I always
enjoyed reading the jarring parts were they describe something that definitely
did not make it into the implementation, or got removed later. It’s
interesting to think about why they considered those things important enough
to write down at the time.

Now that I wrote the above, it's a bit sad that there aren't many design docs
for open source software, even ones that originated from companies with good
design doc culture. Where's a doc that discusses alternatives considered and
rejected for kubernetes or grpc?

~~~
jbeda
I wrote a design doc/PRD for k8s that outlined the basic API, distributed
structure and why/how it related to open source and the marketplace. I lost it
when I left google. It was a google doc IIRC and wasn't checked into source
control.

~~~
robk
Someone must have shared access to find it for you though?

------
dgb23
Related: [https://www.joelonsoftware.com/2000/10/02/painless-
functiona...](https://www.joelonsoftware.com/2000/10/02/painless-functional-
specifications-part-1-why-bother/)

My opinion:

If you don't specify things in a separate document in the form of text and
pictures, then you end up doing it anyway but ad-hoc.

Your "non-spec" now leaks into multiple tools and channels that likely don't
talk to one another: emails, instant messages, file storage, notes, phone
calls & discussions (AKA in your head/memory), Trello/Asana/Jira etc. and in
peoples imaginations and expectations.

A specification is just the things you do _anyway_ but instead written down in
a single maintained place. You can source control it and iteratively change
it. All the parties can pull it and look at it before/during/after iterations
and discussions.

A spec doesn't need to be set in stone at all. It can grow/shrink/change
iteratively with the thing you build. It can also define things that you
specifically shouldn't do or worry about.

A "design doc" seems to be something like that with a different name?

Also a specification can help to communicate much more clearly, since you end
up defining a _vocabulary_ for processes, UI elements, technical components
and so on.

Tools I find useful to do this:

\- markdown + css + some tool to convert it to html/pdf

\- graphviz, especially for state-machines and decision trees, I prefer output
as SVG rather than PNG.

\- UML diagrams or similar if applicable

~~~
H8crilA
A design doc is not exactly a spec. It is a medium for discussion and a
snapshot of what people thought at the time. They do get old pretty quickly
and there's no expectation that anyone will update them (always put dates on
such documents!).

I think that specs should be checked into the codebase, either through some
kind of code annotation, or next to it in text files, depending on what is it
that you're doing.

~~~
dgb23
Thank you for clarifying. My question is: when do I need a design doc, given I
already have a maintained spec? Would they be used for as drafts or are they a
complete separate thing?

~~~
joatmon-snoo
I tend to reach for a design doc when I have (1) an ambiguous problem, (2) no
obvious solution but N possible candidates, and (3) need feedback from
multiple parties.

The primary functions (as people have mentioned elsewhere) are to (1) drive
consensus and (2) record thought processes at the specific point in time.

------
bruckie
I find design docs really useful, even if no one else reads them, because they
force me to clarify my thinking before I start the (more expensive) process of
implementation.

However, I've also noticed a couple of very common problems with design docs:

\- Many design docs don't clearly state the problem that the design is
intended to solve. Often the best response to a design is "that problem isn't
important to solve", or "there's another system that already solves this
problem", or "there's a totally different approach that you should consider",
but without a clear statement of the problem and why it's important to solve,
it's hard to determine those kinds of things.

\- People often focus too much on the details of a design, vs. the important
decisions that need(ed) to be made, the alternatives and rationale for those
decisions, and the assumptions that they were based on. In a year, you
probably won't care that much about the details of the parameters of some API,
but you probably will care a lot about why you chose that API over some other
one, and it's useful to have a record of that decision.

It's useful to view a design doc as a distillation of the thought process
behind a system, vs. a high-level description of how to build something.

------
commandlinefan
I like the idea of design documentation, but in 30 years of software
development experience, I've never seen one done well. TFA does a reasonably
good job of outlining what you'd want from an ideal design document but
doesn't offer any advice on creating one that actually meets these criteria.

~~~
gowld
Same could be said for code, right? It's a great idea, but in 30 years we've
never seen code done well.

"Well" is a slippery word.

~~~
commandlinefan
But code actually works (eventually, usually). If you don't have code, you
don't have software. If you don't have a design document... it's usually the
same as if you do have a design document.

~~~
etse
In my experience, it’s not the same. Design docs allow a dialogue about the
resulting code that code reviews are poorer at or less efficient at. Those
conversations have saved us time and gives us confidence that the solution is
the best for the problem.

------
kcudrevelc
I've worked at Google for a while, and a few years ago I wanted to release an
open-source project. Since the code was going on Git, it made sense to throw
the design there too, so I just added a DESIGN.md to the top-level of the
project. This has had a remarkably nice effect: sometimes, when people make
large changes to the project, they update the design to reflect the changes!

See this lovely commit as an example:
[https://github.com/google/stenographer/commit/d678531a3e5a87...](https://github.com/google/stenographer/commit/d678531a3e5a87b321e9247ba60d0019768681de#diff-6a735bf86dcc8fb712e11c207df01ae4)

------
time0ut
Great article. I spend a lot of my time writing design docs these days. We
derive a ton of value from it.

The projects I work on are typically collaborations with several developers.
It is important to all have the same vision for what we are building. A good
design doc is a vehicle for a team to sync their mental models of the thing
they are building.

We also often have many other teams (security, infrastructure, operations,
other business units, etc) who all have a stake in what we are doing. A good
design doc helps build consensus with them. The review process gives them a
voice in calling out concerns. It is much easier to solve a foundational
problem before any code is written.

One addition that isn't explicitly called out by the article, but I have found
very valuable, is the inclusion of references. In my experience, good design
docs typically include some references. Links to the docs for a piece of
software we want to use, links to an AWS blog post explaining part of the
architecture we want to use, links to academic papers explaining the
algorithms we want to implement, etc. Good references support the design doc
and help readers fill in knowledge gaps they may have.

~~~
bigbizisverywyz
>It is much easier to solve a foundational problem before any code is written.

This brings to mind the 1-10-100 rule. It takes 1 unit of effort to fix a
problem in design It takes 10 units of effort to fix a problem during
development. It takes 100 units of effort to fix a problem after going live.

------
the_arun
Do we have any templates for design docs created by Google, Facebook, Twitter
etc.,?

Not to be negative - My problem is there is no spec/standard template for
design docs (like someone compared it with Blueprints). If we have a template
approved by industry leaders - it will be convenient. Otherwise everyone
creates them in their own way - convenient for their use cases. But this will
miss the consistency and all necessary ingredients. This ends up these docs
fading out with time.

Also, when design changes - these docs need to be updated. People don't do
this. After a while, design docs become obsolete & overhead.

~~~
thebrokencube
I think if there was a rigid spec, it would work against one of the points
made early on in this doc (which I think is worth taking note of):

> Rule #1 is: Write them in whatever form makes the most sense for the
> particular project.

This is an unsatisfying rule, but I think it's important because each
team/problem space/etc. is different and too strict of rules can often lead to
documents that may end up being shallow.

However this admittedly doesn't help with this other problem you brought up:

> Also, when design changes - these docs need to be updated.

... but that may be okay given a shared understanding of what the goal of said
document is. If the goal is to gain consensus around an implementation (as
opposed to it being a living document), the document may have served its
purpose by the time that consensus is reached, even if later on the design
changes. If the goal is to have living documentation of a system, then maybe
the rough format specified in this article isn't correct.

One term I've heard for design documents is that they end up being a piece in
a "Decision Log", which has helped me feel less bad if the document falls out
of date. These documents end up being more point-in-time representations of
the collective understanding/opinions of how a specific project/system was
being thought of, and that has its own advantages even if it falls out of
sync.

~~~
brown9-2
The first points here are absolutely correct. These documents are a way to
communicate and get feedback (and iterate) on an idea with a group of people
in your organization. Different organizations will communicate differently,
and have different needs.

------
PascLeRasc
Does anyone know where to find real examples of design docs, possibly
following this guide? I don't mean toy examples but something that's actually
used by real people/orgs. My workplace has design docs but they're full of
made-up words, so I'm pretty burned out by this kind of thing.

~~~
Offpics
Deno design doc for example
[https://docs.google.com/document/u/0/d/1_WvwHl7BXUPmoiSeD8G8...](https://docs.google.com/document/u/0/d/1_WvwHl7BXUPmoiSeD8G83JmS8ypsTPqed4Btkqkn_-4/mobilebasic)

~~~
PascLeRasc
Thanks! That was interesting to read and gives me hope for a better workplace.
So it's basically a much more thought-out Github issue/corresponding PR, would
you agree?

------
cramforce
Author here. Let me know if you have questions or feedback.

~~~
fbunau
How do you get teams that have knowledge on a particular piece put in the work
when it is not one of their goals / focusing on other things ?

~~~
numbsafari
What really helps here is adopting a culture of shared ownership. If a team
has knowledge, your best bet is to work with them to share it with you. But if
they are too busy, or otherwise unwilling, then you will be forced to move
ahead without them. You can't let teams like that become a bottleneck to
progress.

Similarly, if you are on a team that has important knowledge, it's really
important to share that knowledge widely. Prepare lots of good resources to
help spread that knowledge. Don't try to operate as gatekeepers or a cabal,
instead, it's up to you to be an advocate and an activist for your knowledge.
If you want other teams to respect your team's knowledge, then you need to
make sure that they recognize that you have it, and that you are willing to
share it. Lastly, it's best to adopt a strategy of empowerment, rather than
ownership. Encourage and support consumers of your knowledge to help
themselves, rather than requiring you to opine on every single question, or
participate in every single design review.

All of this, of course, takes leadership, because it's a cultural practice.
Leadership has to invest in having teams document and share knowledge.
Leadership has to reward and recognize knowledge sharers while similarly
recognizing and working with knowledge hoarders to change their ways.
Leadership has to identify when a team has become a blocker on progress and
either add resources, or as noted above, encourage teams to work around them.
"So and so is the networking expert but he won't help us fix this problem."
"Okay, I'll work on getting his time, meanwhile let me find this outside
consultant _or_ I'll give you cover to do the work yourself since they are
blocking."

That last thing is your last resort, but you need to not be afraid to use it.
I actually get the impression that Google suffers from that quite a bit (the
existence of Principal Engineers who "squat" on problems is one I've seen
discussed repeatedly by former employees, and something I've witnessed on OSS
projects).

------
justicezyx
Hah, design docs at Google...

I read probably hundreds of deigns docs during my 6 years at Google.

I think among them, only a handful of design docs, like < 10, are considered
clear, clean, and succinct. And all of them are more or less retrospective
ones summarizing a system after it's already being implemented and running for
a while.

The newer design docs, which are served as actual working documents for an
active projects, are no doubt primarily a _process mechanism_ to solicit
design inputs, and garner supports from stakeholders.

It is a formality to show that the project owner is willing to _waste_ his
time and to convince so-called "reviewers" about the validity of the project.
The reviewers usually do not read the design doc in earnest. Only the
stakeholders, like the TL of the team, potential customers, partners, would
spend serious time on them. It's more or less a debate ground for stakeholders
to pointing fingers at the design process. That's also why the design doc is
written in Google Doc in the first place.

Once a design is "approved", it usually means from most major share holders
are satisfied, to everyone is wearied down enough and the project has enough
importance to actually push forward, they are OKed for implementation.

After that the design doc is largely useless, the designs laid out in the doc
is usually 1) too simple that there is no need to consult design doc anyway,
one can explain it in a few minutes chat; 2) too complicated that the design
diverges from the actual code that the design doc offers little guidance. And
very few design docs sit in between.

All in all, anything produced during a software engineering project seems all
is about being a tool for organizing the human interaction process, the
artifact, aside from a very high-level motivational piece, and the end result
code + docs, whatever in between seems largely bears little value after the
work is done.

------
wsetchell
The article does not point out how the system can go astray.

Design docs are great when they can in 1-2 pages describe a how an
important/large/complex system will work and the tradeoffs made when designing
it.

Some groups in Google confuse design docs conflated with the promotion
process, and thus engineers start create long/time consuming docs for every
little thing as part of building a case for promotion.

------
Slump
Great article, generating consistent design docs that are both useful and not
too time-consuming to create is something I am constantly working on. One
thing I struggle with is finding examples of what others are doing in the
industry. Does anyone have any resources they've found that provide examples
of real-world design documents? Obviously each project is different but I'd be
curious if others out there are publishing their templates/outlines of what
they typically start with similar to this article.

I feel like blog posts seem to serve this niche for a lot of open source
projects but it would be interesting to see if anyone has found more
structured examples.

------
Ozzie_osman
Honestly I sometimes write a design doc even if no one else will read it. It
can be as short as a few sentences, if needed.

The main benefit is it forces you to:

1\. Think strategically, not tactically, about what you're about to build.
Beyond just "I need to get this working now".

2\. It makes sure you can describe what you're about to do in plain English
(or plain English plus some diagrams). If you're struggling to do that it's
probably a sign you need to rethink your approach.

Obviously, the organizational benefits described in the link are really
important, too, but if all you've done is just 1 and 2 above that's already
worth your effort.

------
whoevercares
Frankly I think Amazon has a even heavier design culture. The designs for a
new project (e.g to be launched at reinvent) could go as long as more than
half year.

~~~
koheripbal
Does duration really measure depth of design?

~~~
whoevercares
Yeah some are churns from reviewers, partner teams or even politics. The depth
of the design are commonly pretty deep to the ground, because Amazon has many
SDE1s with relatively low hiring bars and the design need to be super detailed
for a safe execution

~~~
akhilcacharya
> SDE1s with relatively low hiring bars

as an SDE1...yikes dude.

~~~
whoevercares
Sorry I mean compared to Google/FB... But that doesn’t translate to
productivity though

~~~
akhilcacharya
Again, that's a major yikes. I really don't think many others like me enjoy
being called, er.., dumb.

------
gregdoesit
“Unstructured text, like in the form of a design doc, may be the better tool
for solving problems early in a project lifecycle, as it may be more concise
and easier to comprehend, and communicates the problems and solutions at a
higher level than code.“

I could not agree more. I came across the concept of design docs consistently
used for all projects at Uber. They were called RFCs here and they were
introduced very early on. I wrote in more detail about my experience using
these and how I am pretty sure they helped scale the engineering culture [1].
The most surprising thing I’ve observed is how sending these design docs out
to all of engineering worked really well, until the org was over a thousand
engineers.

[1] [https://blog.pragmaticengineer.com/scaling-engineering-
teams...](https://blog.pragmaticengineer.com/scaling-engineering-teams-via-
writing-things-down-rfcs/)

------
choppaface
It would be great to see some actual design docs in a blog post versus a
summary article with zero primary references. (A postmortem of some design
docs would be incredible!).

One of the hardest things about introducing a design doc process to a team of
engineers is providing concrete examples as seeds and ensuring feedback to
make the process actually work. It can be really jarring to introduce the
design doc philosophy to a larger team if all they've been doing is Scrum
every week. Moreover, typically design docs happen at a quarterly rhythm and
feedback periods can take weeks-- this slow cycle is a major impediment to
consensus and learning.

All this calls for material that speaks to differentiated learning. Extolling
"we do this at Google" is a leaf in the wind.

~~~
floil
Here you go: [https://www.chromium.org/developers/design-
documents](https://www.chromium.org/developers/design-documents)

------
britbull
> Are you unsure about the right software design, and would it make sense to
> spend upfront time to gain certainty?

This is a great question to ask. It's human nature to lack foresight,
especially when you are under pressure from deadlines, but in the long run it
saves so much time.

------
Areibman
>Finally, the overhead of creating and reviewing a design doc may not be
compatible with prototyping and rapid iteration. However, most software
projects do have a set of actually known problems. Subscribing to agile
methodologies is not an excuse for not taking the time to get solutions to
actually known problems right.

Here lies the biggest problem with the article. Most software projects _do
not_ have a set of actually known problems. Agile exists precisely because
it's hard to pin down what problems are, and you learn much more about your
product with gradual experiments than with some grand, centralized design.

Unless you are totally certain about your solution, design documents don't
have a place for most projects.

~~~
theptip
I don't agree with this viewpoint. Agile is about just-in-time design, not no-
design.

At some point, you need to decide what the next increment you're going to
build is. Before you write the code for that increment, you have by definition
picked an actually known problem to solve, and for that you should write a
design doc.

I think what you're objecting to is the waterfall concept that you would write
a design doc that covers the whole project, rather than just designing what
you're going to work on next. I can wholeheartedly agree with that objection.

However everything in the article is consistent with epic-level or story-level
design. As the complexity and cost of change increase, more up-front design is
appropriate. None of that is incompatible with the agile tenets of building
small increments and delivering them often to make sure that they add value.

If you're lucky enough to be working in the early stages of a project with a
few thousand lines of code, and little to no production data on which to
maintain integrity, then the value of formal design docs goes way down. But
it's important to know that you'll need them later.

~~~
nawitus
Are you suggesting to write a design doc every sprint, e.g. two weeks?

~~~
theptip
In some sprints my team will write multiple design docs, though that's
uncommon. For example, if we're building two new features, and each is self-
contained. Those design docs are probably small.

In other sprints, we won't author any new docs, for example if we're
implementing and shipping/demo'ing chunks of a large, complex feature for
which we've already completed the technical design.

I'd suggest coupling design docs to stories/epics, not sprints.

------
blululu
This is a very optimistic presentation of design docs. The flip side is that
these documents can become a touchstone for bike shedding or and excuse to
make slideware in lieu of software. A lot of administrative bloat can creep in
through design docs.

------
winrid
At a medium sized company/startup that follows this pattern. It works really
well.

Much better than the core platform team just going and changing a bunch of
stuff every release with no documentation, which I've experienced consistently
at my last job.

------
vngzs
IMO the ideal format for conveying this information is to show, not tell. Give
me an example document and annotate it with sidenotes that describe the
purpose and importance of each section.

Then we get to see how well it works, not leave it up to imagination.

------
jhallenworld
Design docs should be written in Markdown and stored in git. The advantage
here is that the git hash can be used as a legal reference, for example in the
case where a contractor is expected to implement the design.

~~~
dilyevsky
I’ve tried this and I tried just gdocs like everyone at google did. Gdocs
seems better for iterating because github review ui sucks (and everyone else
sucks even more). If google critique was publicly available I’d much prefer
markdown for designs

~~~
pmb
The best is to get agreement on the design is gdocs and then export it to
Github so that the design and code live next to each other.

------
jkaptur
It's important draw a distinction between a "design doc" and "documentation".
tl;dr: "ought" vs "is".

A "design doc", as described in the article, is a tool to help _make a
decision_. It's a proposal. It is "ought". It describes the state of the world
at a point in time, the desired change, and how to make it. Once the decision
is made and the work is begun, it's rarely updated.

"Documentation" is just _the state of the world_ (generally "now" or "at
release x.y"). It describes the design and use of the system, but has very
little digression into ways it could be different. If it links to a design
doc, it should be for

Once you draw this distinction, it's clear that design docs should be in
something like Google Docs, while documentation should be in something like a
wiki or git. It's clear why it's fine for a design doc to be out of date, but
it's a big problem if documentation is. etc.

------
eximius
Half the time these are written after the fact (or updated after major
changes), so they're often used as shitty documentation. I don't disagree with
them, in principle, but I've yet to really see the benefit of them. The adage
"In preparing for battle I have always found that plans are useless, but
planning is indispensable" seems to apply.

------
maps7
This is awesome! Thanks for posting - I think I can use this where I work. I
am wondering though.. how do you allocate time to work on the design doc? I'm
sure sometimes it takes a day but other times it can take longer and if
there's a review needed then it would take even longer. I work in a
agile/scrum team - how would this work fit in there?

------
cborenstein
Design docs are great because writing them is aligned with the author's best
interest, not just a future reader. (This is different from docs that are
written after the project is complete).

Design docs help you understand the project, identify dependencies, and avoid
repeating work. Then they leave a trail for future engineers of the thought
process that went into the code.

------
jp42
After reading this article I can relate it event trace (Chrome tracing) design
doc form google, very succinct to the point:
[https://docs.google.com/document/d/1CvAClvFfyA5R-PhYUmn5OOQt...](https://docs.google.com/document/d/1CvAClvFfyA5R-PhYUmn5OOQtYMH4h6I0nSsKchNAySU/preview#)!

~~~
jeffbee
That is not a design doc, that is a format specification. It jumps directly to
the implementation details without discussing the motivation. The reader has
no way to evaluate the utility of the example JSON because the doc has not
stated any use cases.

~~~
cmrdporcupine
And frankly that's how most of the design docs at Google really are. They're
post-facto descriptions put together for the purpose of gaining promotion.

~~~
jeffbee
Yes and the way you can tell is the doc title is "FooBar Design Doc" but the
shortlink is "foobarforperf".

------
nkingsy
The emphasis on trade offs is the most important part for me, because it
formalizes the search for alternative approaches. In the majority of my design
docs, I end up swapping an “alternative” into the doc itself as I find myself
more convinced by the alternative solution.

------
mediocreguy
Any good examplars of docs that use this format?

------
petejames
Writing helps you think. In the process of creating a design doc you get
clarity of thought and refinements happen.

------
lowiqengineer
I wonder why the "at Google" is necessary for the title. I'd be very surprised
to see an organization not use some sort of design doc before building things
- the only thing that would be different is the scale and scope of them.

Of course, you won't see a "Design Docs at Amazon" on the front page of HN
for...some reason. Gee, I wonder why?

~~~
AnonC
> I'd be very surprised to see an organization not use some sort of design doc
> before building things - the only thing that would be different is the scale
> and scope of them.

There are companies that use agile methodologies and eschew any kind of design
documentation (they kneel at the altar of working code, and working code
alone). I’ve seen teams just discuss things, get a few inputs and start
writing (working) code and pass it through testing. The design process exists,
but there’s no document or documents for anyone to refer to. There may be high
level architectural documents, but not what many people understand as “design
documents”.

~~~
sateesh
I always wonder how such an approach works towards building maintainable
software whose scale is not trivial. Even assuming the code is reviewed unit
tested, but still without some kind of design doc guiding the overall
structure, and interactions wouldn't it lead to hard to maintain software ?

------
rckoepke
I'd love some examples of real-world design docs.

~~~
mbakke
The Ganeti virtualization toolkit which was developed internally at Google and
released as free software is full of such design docs. I always enjoyed
reading those as an external Ganeti user:

[http://docs.ganeti.org/ganeti/master/html/#implemented-
desig...](http://docs.ganeti.org/ganeti/master/html/#implemented-designs)

------
juanbyrge
It's a little ironic that the author of that post created AMP...

------
WeNeedDemocracy
At my place of work we probably wouldn’t follow this simply because we don’t
love the design of Google’s products

