How to write an effective software design document

If you're writing a software design document that slows down your delivery timetable, you're doing it wrong. (Or, more charitably, your business is doing it wrong.) If your design document is to keep the business in sync, you're doing it wrong. That's not what a design document is for. It's for keeping you in sync.

> It is often faster to just build the damn thing and see where it lands.

What are you building? If you don't know, then sure, it's really hard to write a design document. At that point, you're doing exploration, research, not development.

But even when it's an exploration project... once you've found something worth doing, take a day or two and document what you're doing and how you're doing it. Think through all the places in the code you're going to have to touch, all the other things it has to interface with. Make sure you're not going to leave a gaping hole in functionality or, worse, in security.

> Software is not like a nuclear power plant or offshore oil platform.

As others have said, sometimes software is a nuclear power plant or offshore oil platform or airplane or medical device, or even just medical informatics. If you mess up people can die. Sometimes it trades financial instruments, and if you mess up it can destroy the company.

> No one actually has to give you permission to do anything.

On your own time, sure. If you own the company, sure. Otherwise, you need their permission to spend their time on things that they're willing to pay for.

Now, look, it's true that many places go too far overboard on "process". But YOLOing and cowboying isn't the answer either. They aren't even the answer if your single goal is to go as fast as possible. You go faster by spending the appropriate amount of time thinking through what you're building, how you're building it, and making sure you're not missing any of the big things that often trip projects up.

This is a good question, and I have a super long answer that's been in my head for like 8 years about how to influence your teammates to adopt good engineering practices.

The short answer is that most useful software engineering practices are a risk to the first person on the team to adopt them. For example, if everyone on your team thinks automated testing is stupid and you adopt automated testing, it will look like your work is worse because you're slower in the short-term, and maybe you have to do even more work when teammates break your tests.

It comes down to accruing social currency with your team. Your teammates don't want to take a risk for you if you have a history of bad ideas that wasted everyone's time. But if, for example, you implemented automated deploys to replace a tedious workflow developers had to do manually, people would see how your ideas have payoff, and they're more willing to invest a little bit if they expect ROI long-term.

When I've convinced my teammates to invest in design docs, I made sure I had some wins under my belt before I started pushing for everyone to write design docs. I invested a lot in docs myself so my teammates could see the value before I asked them to start writing.

This is also a place where you have to think about politics a bit. Documentation has a much better shot if it has support from the top, so think about the pitch to your manager or dev lead about how design docs make their jobs easier.

I've both produced documentation and consumed it. When I consume documentation, I don't expect much. And to be honest, I don't like the low signal to noise ratio in typical design documentation. That was always a problem. Any sufficiently complex thing is just hard into a power point friendly diagram. And anything involving boxes and arrows where the number of boxes is 5 at best, is probably not that interesting to think about.