Advice to Design Document Writers
After having reviewed three ... suboptimal ... design documents this week, I feel I should really say something on the topic of writing up a good design.
I know most of my coworkers don't bother reading other people's design docs, so maybe you're totally justified in going through the motions and churning out total crap to satisfy "the process". But I do. I try to read every one that comes across my desk, spend some time thinking about it, and then send back the best comments I can. I spend a lot of time on it, because I consider it an important part of my job, just as important as coding is. I would hope that you're not jumping off a cliff -- but if you are, I would like the opportunity to say something when you're on the ledge, and not, say, halfway down.
And just to be clear -- we're not talking heavy-duty architecture here. We're not talking about hundred-page tomes of densely written academic arcana. The sort of design documents we're talking about are really no more than one engineer telling another, "hey, I'm about to write the Foo feature, this is how I was planning to do it; tell me what you think". They'd be just as effective if they were simple emails.
So please, I beg of you, write something I can read.
I ask not just for my own sake. Carelessness in writing correlates well with carelessness in thinking. If I can't understand what you're trying to say, I can safely conclude that not only are you a poor writer, but your idea probably sucks too. On the other side of that coin, I've never run into a well-written document describing a truly awful design idea. It's just really hard to write lucidly about something that fundamentally doesn't make any sense. Try it sometime if you don't believe me.
On that note, let me also point out that design review meetings are for REVIEWING DESIGN. It is not for explaining your poor chicken-scratchings of a design document. A random brain dump of disorganized ideas does not a design document make. Sorry. If I can't get a clear idea of what you intend to do from the doc alone, you wrote it poorly; go back and fix it before you schedule a meeting. And this practice of sending out a draft of the design document two hours before the design meeting? Stop it, please, or I will have to hurt someone.
I shouldn't have to go to your review meeting. I usually don't, actually. Some people prefer giving feedback face-to-face, and that's fine, but I actually prefer to use email in order to avoid subtle miscommunication.
And on the same note: again, design review meetings are for REVIEWING DESIGN. It is not for creating new design on the fly. Sure, I know it's tempting -- you're rushed for time, you've got a dozen open issues to close on by this afternoon, and fractious debate just isn't your thing. You don't have the energy to come up with your own solutions and defend them in the meeting. So hell ... why not just leave them all open issues? Surely a gaggle of non-experts can come to a consensus for each and every issue in under 60 minutes.
Again, this is total nonsense, and it needs to end. Don't leave open issues hanging. Coming up with solutions is your job, telling you if they suck or not is my job.
Why Design Documents?
I'm not a Big Design Up Front guy. My philosophy is A Little Thinking Up Front. I distrust TDD as a methodology because it strikes me as too much random-walking the problem space to stumble on an acceptable solution. But I certainly don't condone overthinking the problem either.
To be honest, I actually don't think design documents have much value in and of themselves. I subscribe to the Dwight D. Eisenhower school, where plans are worthless, but planning is everything. A design document should be well-written, not because someone needs to read it, but because the writer needs to be thinking precisely and rigorously if they have any hope of creating a precise and rigorous design.
The end result, however will always be subject to change in light of changing requirements. Contrary to some people I know, I don't see the point of keeping the design document up to date. It violates DRY. The documentation and the code will inevitibly drift apart despite your greatest efforts; it's really not that hard to understand well-written code in the first place, so why not go to the authoritative source directly?
It's a truism that no one reads design documents anyways; if they do read them, it is as a historical artifact -- to get an idea of what one person was thinking at one point in time, and not necessarily what the design is now and eternally should ever be.
On Document Templates
Finally, a word on document templates. Yes, we have a standard document template in my group, and no, it doesn't do a damned bit of good.
Our template is really quite simple. It has four main sections:
- Introduction
- High-level design
- Detailed design
- Other considerations (a dozen items such as localization, performance, security, error handling, etc).
Most people get through the introduction OK. But the distinction between "high level design" and "detailed design" is a total fucking mystery to most folks -- they sort of run into each other in one long ramble. Personally I usually rename them to "interface" and "implementation" respectively: the theory being that once an interface is nailed down, the implementation is pretty unimportant; 90% of the time it practically writes itself.
And no one, but NO ONE, ever fills out the "other considerations" section of the template. Neither does anyone hold anyone else accountable for completing it. Let this be a lesson for document template writers everywhere: you can lead an engineer to water, but you can't make him think.
One of my favorite interview questions is "how do write design documents?" At the risk of tipping off a potential interview candidate to what I think the ideal answer is, here's the template I'd prefer to be using:
- Introduction: what are the background, goals, relevant functional specs, etc?
- Class diagram: who are the major players? What are their responsibilities? What state do they carry?
- Interfaces: tell me about all new public functions, classes and/or interfaces you plan to define. Don't describe private methods and other implementation details: save it for an appendix if you REALLY think it's important to write down.
- Examples: Show me sample code, test code, or sequence diagrams that illustrate how these new interfaces are intended to be used.
- Defense: what other ideas did you consider? What are their pros and cons relative to the design you eventually chose?
- Test cases: are there any tricky parts you think might be difficult to get working correctly? If so, explain ways you can test your design for correctness.
