Design doc template

8

I whipped up a design doc template recently and thought someone else out there might find it to be a useful starting point. For me, I find a lightweight design doc (1-4 pages) to be a really useful way to focus your thinking before diving too far into the code. I’m not a fan of heavy rigid design docs as they typically cause you to waste time writing (or copying …. ugh) stuff that no one will read.

The doc structure should force you to do some of the thinking you’ve been putting off. Then you can do a quick review of that with whoever serves as a stakeholder (customers, product mgmt, etc). At that point, I’m happy to abandon the doc or go through another update cycle, depends on the context. I don’t think it’s worth keeping the doc perfectly in sync with the code after the thinking and understanding phase starts to die down.

Here’s the doc:

Comments

8 Responses to “Design doc template”
  1. Mittal says:

    could not open the document !!!

  2. Josh says:

    Both of the links point to a “.odt” file (which I assume is the OO Doc Template)… but no Word one :P

  3. Alex says:

    Oops! Fixed. The dangers of copy/paste late at night….

  4. Stan says:

    I like your “what do they need to know” question. I’ve always wanted to put this first in the overview:

    _____ reads _____ to learn _____ so they can _____

    If you can’t fill it out, don’t go on. ;-) This seems to have a little too much of everything for everybody, which rarely makes good reading for anybody.

    “describe this feature/task to a greater level of detail than can be done in code” that’s very scary. This information will be LOST in the finished system if it can’t be said in code.

    Requirements and Customer Usage sections seem to duplicate things I’d usually have in another document, in terms the business folks can write, read, validate, etc.

    Priority 1 & 2 mean nothing to me. Hope they do to your reader. :-)

    Test cases restate requirements. Don’t Repeat Yourself. Maybe move them together into a two-column affair – requirement and how to prove you met it. Or – a really radical idea – write requirements as tests in the first place.

    I have to admit I haven’t had much success creating templates anybody actually uses. They look good for the Project Management Office, though.

  5. Alex says:

    @Stan: This doc is more of a set of possible topics. Generally for a particular feature only some of these make sense. The intent is definitely to hit the high points for several audiences (tech, prod mgmt, qa) just enough that everyone can agree that what we’re building is what we need.

    For certain projects, this is not enough. For bigger, more critical, or less understood projects, you need to break these pieces out into requirements, design, test plans, etc. My personal opinion is that I’d rather undershoot and review than overshoot and waste time. I’ve found similar templates like this to be a great compromise point.

    The code is always the ultimate description of what the system does, by definition. But I find it is often not the best medium for a descriptive rendering of what the intent of a large chunk of code is doing, particularly on a per-feature basis. An ideal would be to have architectural docs that describe the overall system structure and per-feature docs that take a slice out of the system to explain a particular feature. In both cases, pictures are gold. Neither of these are easy to bleed into code. In practice, I find it unlikely that either of these are kept up to date. In lieu of that, having a statement of the original intent (and rejected alternatives) can be a gold mine at a later date.

    Sure, it’d be great if reqs and customer usage existed in other docs but in my (limited) experience they don’t, or at least not in enough detail. Admittedly, my experience tends toward the lightweight software startup world.

    P1 = must have, P2 = nice to have, P3 = stretch but unlikely.

    I do not expect a full test plan in the testing section. I expect a description of how (at a high level) testing will be accomplished, maybe a list of test ideas from a brainstorming question, existing system tests that can be leveraged, etc.

    I’ve used similar forms of this template in two previous jobs successfully. I’m happy to work in a company small enough that the idea of a PMO elicits a hearty laugh.

  6. LudoA says:

    Could be helpful, although a template to help customers explain their needs/what they expect of a feature/… would be even more useful, IMHO. But I guess that’s too project-specific…

  7. Jon Ranes says:

    Thanks for this. I have just started freelancing after being a corporate developer for 10 years. I needed a simple doc like this without all the fluff and bull. Thanks!