Design Docs at Google • Hacker News Board

Re: Design Docs at Google

#141

Post by DEADBEEFC0FFEE » Wed, Jul 22, 2020, 9:36 PM UTC

sarchertech wrote: post #39

cameronbrown wrote: post #38

Earlier quoted context omitted.

I mean, you're right... but the goal of an analogy isn't to be perfect, but to be a rough mental model to quickly express a concept. I think it's fine. Different jobs require different levels of abstraction and design docs fulfil that role for software engineers.

Yes models can be helpful even if they aren’t perfect. But not only is this one too far off to be useful, it does more harm than good. The expectations that happen when people (specifically managers) start thinking of design docs as blueprints, software architects as architects, and developers as builders are downright dangerous.

Models are always imperfect.

Re: Design Docs at Google

#142

Post by [deleted] » Wed, Jul 22, 2020, 9:47 PM UTC

commandlinefan wrote: post #17

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.

[deleted]

Re: Design Docs at Google

#143

Post by mbakke » Wed, Jul 22, 2020, 9:51 PM UTC

rckoepke wrote: post #133

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

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

Re: Design Docs at Google

#144

Post by mbakke » Wed, Jul 22, 2020, 9:55 PM UTC

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.

I've been a long-time user of a Google virtualization toolkit that was developed in the open. It is full of such design docs:

http://docs.ganeti.org/ganeti/master/html/#implemented-desig...

As an end user I always enjoyed reading those.

Re: Design Docs at Google

#145

Post by dgb23 » Wed, Jul 22, 2020, 9:56 PM UTC

H8crilA wrote: post #135

dgb23 wrote: post #51

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/A…

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.

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?

Re: Design Docs at Google

#146

Post by floil » Wed, Jul 22, 2020, 10:14 PM UTC

choppaface wrote: post #128

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

Here you go: https://www.chromium.org/developers/design-documents

Re: Design Docs at Google

#147

Post by TeMPOraL » Wed, Jul 22, 2020, 10:18 PM UTC

javier10e6 wrote: post #124

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…

I agree wholeheartedly. The best software documentation is the an actually well written software module + test that explains its functionality.

Let's not forget about comments.

A well written piece of code will only tell you what it does, a good suite of tests will teach you how to use it, but only natural language documentation - be it in comments or separate documents - will explain to you why the code exists in the first place, and why it looks the way it does.

(As for "self-documenting code", unless a lot of your functions contain the word "because" in their name, the code isn't really self-documenting.)

Re: Design Docs at Google

#148

Post by maps7 » Wed, Jul 22, 2020, 10:22 PM UTC

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?

Re: Design Docs at Google

#149

Post by maps7 » Wed, Jul 22, 2020, 10:25 PM UTC

dgb23 wrote: post #145

H8crilA wrote: post #135

Earlier quoted context omitted.

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.

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?

I think a design doc is for when you don't know enough to spec a solution.

Re: Design Docs at Google

#150

Post by maps7 » Wed, Jul 22, 2020, 10:28 PM UTC

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 work in an agile/scrum team. Do you have any experience in tracking the design doc work in this type of environment? It's hard to estimate how long a design doc would take since investigation into the solution and conversations with stakeholders could expand it.