Hacker News Reader

Comment by zardeh | 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.

View on HN

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

Reply on news.ycombinator.com