Design Docs at Google • Hacker News Board

Re: Design Docs at Google

#21

Post by mikepurvis » Wed, Jul 22, 2020, 1:38 PM UTC

jakevoytko wrote: post #13

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…

> Navigating organisations and achieving consensus between a lot of teams/technologies is a huge part of it I think this is a major benefit of design docs - they are a way to extend your engineering influence beyond your own individual output. If you write a design, and your design allows you and three other engineers to coordinate your efforts, then your engineering output is now "I coordinated a team to build somet…

> ... uncovering blockers as early as possible is critical when coordinating a bunch of entities.

I think the challenge for me has always been that the "uncover blockers" piece means building one or more small prototypes to prove out the capabilities of the dependencies, check feasibility, etc. So the building of these prototypes occurs prior to or in parallel with the authoring of the design doc, but then at a certain point they get paused so that the design doc can be completed and reviewed, and then picked up again when it's time for the "real" implementation to occur.

But pausing there takes discipline, since it ideally happens at the exact moment when all the main blockers have been cleared away and it is maximally tempting to just step on the gas and start into the work of cobbling the prototypes together into the project.

Re: Design Docs at Google

#22

Post by Offpics » Wed, Jul 22, 2020, 1:42 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.

Deno design doc for example https://docs.google.com/document/u/0/d/1_WvwHl7BXUPmoiSeD8G8...

Re: Design Docs at Google

#23

Post by lhorie » Wed, Jul 22, 2020, 1:44 PM UTC

ChrisMarshallNY wrote: post #16

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

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.

Re: Design Docs at Google

#24

Post by AgloeDreams » Wed, Jul 22, 2020, 1: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.

Basecamp pitches and shaping are kinda like design docs but with a lot of what I found to be lacking here? You might want a look, they they refreshingly human-readable concepts.

Re: Design Docs at Google

#25

Post by gowld » Wed, Jul 22, 2020, 1:55 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.

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.

Re: Design Docs at Google

#26

Post by gowld » Wed, Jul 22, 2020, 1:57 PM UTC

fbunau wrote: post #8

cramforce wrote: post #2

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

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 ?

Pay people for producing value. If you believe design docs have value, pay people more for writing more better ones.

Re: Design Docs at Google

#27

Post by ChrisMarshallNY » Wed, Jul 22, 2020, 2:03 PM UTC

lhorie wrote: post #23

ChrisMarshallNY wrote: post #16

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

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

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

Re: Design Docs at Google

#28

Post by PascLeRasc » Wed, Jul 22, 2020, 2:05 PM UTC

Offpics wrote: post #22

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.

Deno design doc for example https://docs.google.com/document/u/0/d/1_WvwHl7BXUPmoiSeD8G8...

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?

Re: Design Docs at Google

#29

Post by eitally » Wed, Jul 22, 2020, 2:07 PM UTC

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 -- from experience -- that in traditional IT organizations this is absolutely not true. The PMO is responsible for business requirements, and almost not time is invested in the creation of detailed DDs. You're essentially left trying to move from a PRD to writing code ... and if you have the luxury of an in-house SQA team and a relatively effective CI/CD process, you depend on quick feedback from stakeholders to certify whether the guesses and assumptions made by developers are correct or not. Since in many cases the business owner(s) had never actually considered many of the edge cases (stupid, basic example: previous company required CFO approval of all international travel requests. Tool was built with this logic. No one considered how to handle it when the CFO was unavailable for whatever reason, so the first time the CFO went on vacation it created all kinds of stupid chaos while a manual process was created.), flexible logic paths aren't designed into workflow apps. Similarly, for reporting/BI tools, there are frequently gaps between the answers executives want to glean from the data, and the business processes the ultimately result in the data creation. Because of this, nearly all reports are faulty, but unless you're close enough to the processes you don't have explainability and uninformed business decisions can result. Ditto from CRUD apps, where form validation rules can be insanely complex for stupid reasons, with the result being the data entered is impossible to use.

Apologies for the diatribe. Big fan of design docs, but an even bigger fan of software engineering cultures that focus on simplicity and usability, rather than being everything to everyone (or worse, being a pet project of an exec who changes their mind every quarter about how things should work).

Re: Design Docs at Google

#30

Post by commandlinefan » Wed, Jul 22, 2020, 2:09 PM UTC

gowld wrote: post #25

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.

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.

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.