Hacker News Reader

>You shouldn't hire people who don't give enough of a shit to take the big picture into account.

At a certain point you can't. I was recently asked to implement a feature for a usecase for another engineer. It required a design doc and review by a few representatives from related teams. He and I wrote the doc, and the initial review was that any solution that would fix his usecase would break the testing infrastructure for practically every other developer in the building. He could write a few fewer loc when testing, at the cost of tests failing due to unrelated changes.

Neither he nor I had the awareness of the impact, and realistically couldn't have, it was neither of our responsibilities. And because I spent an hour filling out a template document, I didn't need to waste my time doing that.

> break the testing infrastructure for practically every other developer in the building

Why wouldn't continuous integration have caught that bug? If a diff breaks the build, it shouldn't land. If a diff causes tests to fail, it shouldn't land. If a diff lands anyway and causes problems, any developer negatively affected should be able to insta-revert the diff.

How does a design document help?

It helps identify potential problems / conflicts across teams even before a single code is written (or development time committed).

I don't think so. Who looks at design documents? Your own team. If you don't yourself catch that a change will cause problems with other teams, the existence of a design document won't magically alert that team. If you do suspect that there might be a bad interaction with another team, you can alert that team with or without a design document.

So again: how does a design document requirement help?

>Who looks at design documents? Your own team.

At least where I work, no. Your team, your manager, and anyone who you think will be affected, and depending on the scale of the change, you inform everyone that uses your tool or works on your product so that anyone can provide comments and feedback.

You're making the assumption that other teams and other leaders won't review your docs. In my experience, they do and always come back with more questions.

> If you do suspect ...

And that's exactly it. If I suspect something then of course I can communicate it directly or redesign, but we're trying to assess impact on areas I might not have no awareness of.

So let's put it in another way:

Design docs is one of many formal methods of communication in any organisation. It preserves context, change history, and a good part of risk management. It protects you and potentially saves downstream rework.

I missed this earlier, for reference, with this specific problem, I was intentionally modifying part of the continuous build pipeline, specifically, I was working on a tool to autogenerate certain tests in certain contexts. This was eventually possible, but the first request as to how I solve the problem would have been bad.

Feedback from a team that worked with another tool we used in the testing process informed me of the potential for the problems. To be clear, this would have eventually happened anyway, its unlikely that a PR breaking the CI system in this way would have gotten approved, but there would have been much wasted effort on my part in the interim.

> You shouldn't hire people who don't give enough of a shit to take the big picture into account.

Even if you care, you can't know the entire story. I work for a small company, tiny compared to Google, but often we run into someone proposing a change that backtracks on a strategy decided 2 years ago. Luckily it was encoded in a design document or else, how would anyone new find out about it?

New people want to know the big picture, but the best way to do that is to write about your decisions as you are making them, and give them some sort of searchable record.

Personally, I love Github because while you don't have formal design docs---you do have a history of the entire argument of why a feature should be implemented, followed up with a history of all the breaking changes caused by it, and the final reversion. It's great to plunge into a codebase, and see how did we get there, before deciding to propose something.

Have you ever been on a team, and proposed something only to hear "yes we tried that, it failed for X,Y,Z reasons... but no we never noted down starting this 6 month initiative down anywhere except my head".

> backtracks on a strategy decided 2 years ago

Why should anyone be bound today by decisions made two years ago? Maybe that strategy no longer makes sense.

I've seen it go both ways. On one hand, sometimes a new developer in an old codebase does something "against the grain" of the system due to unfamiliarity or JavaScript-induced brain damage. On the other hand, sometimes circumstances change and even good old designs become obsolete.

A culture of good taste and transmission of institutional knowledge helps preserve the good aspects of design. I don't think design documents help: they're just bytes on a disk. Unless you have people to enforce them, these documents won't do a thing. If you do have people who know what the system is supposed to look like and who shepherd changes to work with the original design, you don't need the design document.

> Why should anyone be bound today by decisions made two years ago? Maybe that strategy no longer makes sense.

Then that'd be a great time to discuss that the strategy should be changed, and move forwards as a team---not a single developer deciding to go against the grain with side effects that may be unknown.

Here's an example:

At my company it's our strategy that all file operations happen atomically and asynchronously. Even if your function was the one to create a temporary file, and you are absolutely sure it's happening locally, deleting it must be an asyc task handled by another worker.

Why? Because historically, small tasks start off as local only operations, but get upgraded to handle remote instances. Remote operations can fail fairly often, and we don't want the entire task chain to die because you couldn't delete a temp file on another server.

Now .... to any single developer writing a small script, this feels inane because forcing it to a asyc op, using our message bus tool chain, etc. will slow down the entire function by an order of magnitude. But it saves on 10x more integration work 6 months from now that they don't anticipate.

You don't know everything, and if you do, your replacement 3 years from now won't.

Engineering is a process to solve problems at its core. Fundamentally, you cannot solve problems without know on what the the questions are.

> When you ship every week, you can easily undo mistakes, and you're better off erring toward iteration.

Or so they thought: http://pythonsweetness.tumblr.com/post/64740079543/how-to-lo...