What's a spec? What's a design doc?

by Michael S. Kaplan, published on 2005/01/04 00:30 -05:00, original URI: http://blogs.msdn.com/b/michkap/archive/2005/01/03/346090.aspx


A couple of definitions here -- though of course these are not official throughout MS (there is no common standard definition across all of Microsoft, nor could there be!).

Spec -- The specification for a feature. Usually written by a Program Manager (though I have been known to start them off before and I have wriiten one that is about 40 pages that I'll be doing the dev work on soon). The goal of this document is to have enough detail that a developer can cost and implement the feature without being blocked by unclear points, and there is enough detail that a tester can cost and do a breakout with it, without being blocked.

Design Doc -- The Design Document for the feature, Written by a Developer or occasionally a Technical Lead, it is the developer's specification that has the actual implementation plan. In my opinion, a good design doc. will have enough information in it that snother developer can pick it up and implement it, and the original author could revuew the code and get an eerie sense of familiarity about the way it was  implemented.

Obviously for these documents to be good, there will need to be heavy feedback from program managers, developers, testers, and often other interested experts from UE and localization. Although customers would not usually be reviewing either one, as good spec. will contain information about the feature's scenarios based on customer contact (be it usability tests, focus groups, user group meetings, conferences, newsgroups, blogs, the MSDN Feedback Center, or messages sent by carrier pigeon.

Now these things are unfortunately not always done and are sometimes done after the next step is happening, which is not as bad but is still far from ideal. The better they, are the more likely the feature is to succeed.

The one major exception I was involved with I discussed yesterday was only an exception because a ton of program mamager feedback was used to shape the prototype -- and although I think the result was good, I think it took a lot more work to make it so (and a lot of time from the tester to get unclear issues resolved).

The lesson was learned - next time there will be a spec and there will be a design doc.

This post was sponsored by "Æ" ( U+00c6, LATIN CAPITAL LETTER AE)


no comments

go to newer or older post, or back to index or month or day