Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Design Docs at Google

industrialempathy.com

Post reply on HN
Print view View original

51–60 of 191 posts

Re: Design Docs at Google

#51

Post by dgb23 »

Related: https://www.joelonsoftware.com/2000/10/02/painless-functiona...

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

Re: Design Docs at Google

#52

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

Re: Design Docs at Google

#53

Post by supahfly_remix »

nickbauman wrote: post #43
sarchertech wrote: post #35

Earlier quoted context omitted.

>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 specif…

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.

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.

Re: Design Docs at Google

#54

Post by AnonC »

lowiqengineer wrote: post #50

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?

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

Re: Design Docs at Google

#55

Post by yegle »

PascLeRasc wrote: post #20

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.

The author of Beancount (a text based accounting software) is a Googler and he recently shared https://docs.google.com/document/d/1qPdNXaz5zuDQ8M9uoZFyyFis... which is a pretty standard Google style design doc.

Re: Design Docs at Google

#56

Post by sateesh »

AnonC wrote: post #54
lowiqengineer wrote: post #50

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?

> 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) cod…

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 ?

Re: Design Docs at Google

#57

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

Re: Design Docs at Google

#58

Post by sanderjd »

supahfly_remix wrote: post #53
nickbauman wrote: post #43

Earlier quoted context omitted.

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.

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.

I think they were using "design" as akin to the blueprint to the building. I totally agree with them that in that sense, the code is the blueprint, not the building. The execution of the program is the analogy to the actual construction: the builder (computer) takes the blueprint (code) and builds the building (executes the program) based on it. The power of computers is that the "building" (execution) part is essentially free and infinitely reproducible. But the creation of the "blueprint" (code) is still labor intensive.

The right analogy for design artifacts really is to the higher-level vision definition for a project. Engineers don't just show up and start drawing blueprints; one or more people come up with a purpose and concept for a building project, brainstorm approaches, evaluate trade-offs, come to some consensus on the right direction, and only then start working with engineers to start creating and iterating on blueprints. This vision phase is where design docs fit.

Re: Design Docs at Google

#59

Post by bbeekley »

jhallenworld wrote: post #36

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.

We did this at a previous company in the healthcare space. It made audits easy since we could point to every instance of the design changing, who approved it, and the code that implements the change (all wrapped up in PR(s)).

In general I like checking docs into source control, for all the reasons we use git and code reviews for the code itself.

Re: Design Docs at Google

#60

Post by sanderjd »

Aperocky wrote: post #5
cameronbrown wrote: post #4

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 c…

> I know this is fairly controversial, but our jobs isn't just to write code. I don't know if this is actually controversial, but I would not want to work at a place where this is controversial.

I think this myth comes about because early in peoples' careers, the expectations of the job are a lot more focused on writing code to execute a vision defined by someone else. It is easy to get the impression from this that writing code is viewed as the most important part of the job. But in reality, it works this way because the opposite is actually true, the more important non-coding parts of the job are being entrusted to more experienced people (often to their chagrin, because writing code is way more satisfying and fun).
Post reply on HN