Hacker News Reader

That must have changed. I worked there from 2006-2014, back then most design docs were useful and followed the basic structure described in the article (minus the system context diagram).

I noticed early on though, that design docs maintained in Google Docs tended to be of lower quality than those maintained in the version control repository. Not sure if that was just a proxy for when they were written or whether the code review process is just more rigorous than editing things in Docs, but the only time I wrote a large (40 page-ish?) design doc I did it using hand written HTML and we worked through the code review system, as was traditional. I also posted it to the central mailing list and web server and got feedback from employee number 3, which was nice. The central location made it easy to find them as they were sorted by category.

Still I don't recall design docs being important enough to matter for a promotion by themselves. Promos were supposed to be about overall impact, not production of specific artifacts. Of course the system was badly flawed, and often yielded surprising decisions in a bad way, but I don't remember ever reading an obviously-optimized-for-perf design doc back then.

If you can find the website that holds the design docs hand written in HTML from the earlier years, try perusing some of those and see if you find them more useful (or would have done when the systems were contemporary). Some of them old ones like SmartASS were full of detailed explanations of the underlying equations and models, which was quite helpful for understanding how it worked, as well as the explanations of why those approaches were chosen. Reading those helped informed my own design work later. I wasn't a director, just an engineer, and they did help.

There are also some Chrome design docs linked to from the chromium.org website that I found helpful in the past for understanding its design.

> Still I don't recall design docs being important enough to matter for a promotion by themselves. Promos were supposed to be about overall impact, not production of specific artifacts.

How can you prove "impact" to a committee who otherwise doesn't know your work, without providing evidence in the form of docs, code examples, and other artifacts?

Traffic, revenue.

That leaves out a lot of work that folks do that don’t affect either of those directly.

Yes the most common complaint about any incentive system that rewards "impact" is that it's hard to demonstrate for some kinds of jobs. I started in SRE ("devops") and then later moved to anti spam and security, so had to find alternate ways to demonstrate impact.

Still, the intuition is obvious enough. If you don't tie incentives to some sort of verifiable impact on the business then a lot of people end up doing make-work in which the appearance of doing work substitutes for actually being useful. As this wider thread is complaining about, in fact.

A common form of this complaint can be found in any business that makes software, that refactoring or "tech debt" style work is hard to justify via business oriented metrics. There's some truth to that, but also I came to feel that forcing people to find some sort of business-related metric they're affecting helps keep engineers honest. When to take on and when to pay down tech debt is one of the most nuanced and difficult subjects for any engineer to learn on their path to seniority, and becoming obsessed with refactoring is one of the most common failure modes along the way. Saying "but how did this actually affect the business" forces a reality check that can help avoid doomed rewrites and other pathologies.

For example, Google has a system that automatically finds and deletes dead code. This is the sort of thing that at first seems hard to justify, but with a bit of work you can do it. Work out the overall eng cost of maintaining each line of code (some napkin calculations are fine), work out how much code you're able to delete, work out the cost of developing the auto-deleter system, show that money spent on maintenance of dead code > cost of developing the system. Business impact demonstrated, done.

It doesn't have to be monetary either. I never demonstrated monetary impact. It was all things like "contributed to the launch of X that increased traffic by Y". In the case of the security and antispam work it was "successfully blocked Z attacks against our users", stuff like that. The impact is obvious even if not expressed in dollar terms.

I've seen design docs work when you have a relatively high number of junior roles compared to seniors. It forces the junior developers to think through their solutions ahead of time and justify their decisions, and it also allows senior developers to validate those decisions and give feedback asynchronously.

Granted, I've never worked in an org with more than 30-40 engineers, as I've always worked in startups. I'm sure things are different in big tech, but I've had positive experiences with them.

Need time and effort to ensure junior docs are thorough. Usually multiple revision in my experience. This require acceptance from management that "just write code fast" is not a success path.

Yes! Although I think you forgot one, the "please just let me start coding" doc.

IMO the uses for a technical document (design doc or a shorter doc) is simple. If you get to the point where you can't hold every single detail about a project in your head at once then you should write a doc. Similarly, if it will take a long time (30 minutes at least) to explain to another engineer, you write a doc, to save yourself time.

IDK how you can think that you never need to write a document

My experience has been that the second one means, "I need to communicate with my team/TL what I'm doing/how I'm solving this problem." Eventually, when you go for promotion, you take documents in category 2, and add enough context to them that they become category one.

It sounds like there's no good review process for these; if they lack substance or are too long, they should never be published. But I take it that the people responsible for the people writing these also get the benefits?

There is a review process, but "yes, your comments are relevant, but they're just nit picking, can you just approve it so that we can start working on this project?"

It feels like this case where when people are reviewing each other they might feel incentivised to be easy on each other in agreement so that both would get the promo easier, especially if they both think the doc is just for show to get the promo.

Am I going to be a difficult person here finding each and single flaw about the doc or should I just allow it, let the other person get more visibility and just move on with my work. Why should I be a bottleneck here for a pointless battle.

Spot on haha.

The promo design doc is directly incentivized by managers: “if you just see a bunch of CLs, it doesn’t tell a story. You need to write it down as a coherent narrative and get some >L5s to comment on it”. “It’s not for me it’s for the committee - they aren’t familiar with your work so you need to explain it”.

> But again, they were no engineer, they were a director, I guess design docs make sense for their position

Yeah I think it’s just high potency ammunition in the middle management[1] turf wars. Not even product managers care much about DDs.

[1]: Liberal definition: anyone who uses the word “cross-functional” colloquially, independent of their actual job title.

> There is a wide range of types of design docs, and none of them are useful.

I write them mainly as a tool to get visibility with superiors. I try to make them as fancy as possible to to make them think i am "leadership material". I've been feeding them to chatgpt to rewrite them in fancy language.

If you are a googler, you should be using Bard.

i am trying to get promoted not fired

Red rag to a bull: "this is best practice". Really? There is no better way to do something given more context or experience? A better practice will never be discovered or devised?