Basically my question is what design documents should my project produce.

This can divide into two questions:

  1. What design documents must I produce in order to be in compliance with my companies accepted methodolgies, and how can I make those documents as effective as possible?
  2. What design documents give me the most "bang for the buck"?

I'll assume you're asking the second question.

Either way, design documents can become a big burden on a project, particularly when you try to do a bunch of design up front, but the design migrates as you start to build it and get more experience (or the customer changes their requirements). I favor being minimalistic, and try to avoid throw-away work. The more pages of design doc you write, the more you'll have to update as the system grows. Write down too little, and the design isn't communicated. The trick is to find a balance.

For database systems, the document that I've seen get the most use is a current E-R (Entity Relationship) diagram, stuck up on a wall where everyone can see it, and where people can gather around it and exchange thinking. At lot of micro design can happen by getting the right people in front of the diagram for a stand-up design session.

The key point is that this diagram has to be visible and current. That means that people get to write on it as changes get made, and that you'll need to periodically produce a new version.

The E-R diagram is logical. If you find that you need physical design details, tack up the DDL next to it. I suspect that you'll find that fewer people will refer to it.

Another useful document I've found is a simple log of issues and resolutions. It should provide a way of answering "why did we decide do it that way?" questions, and record enough information about assumptions or trade-offs to be useful when new information is available. A lot of decisions get made in a project, and many can pass by some people unnoticed or unappreciated. The logs I've kept have always proven valuable later in the project.

In reply to Re: Design Documents? by dws
in thread Design Documents? by Anonymous Monk

Title:
Use:  <p> text here (a paragraph) </p>
and:  <code> code here </code>
to format your post, it's "PerlMonks-approved HTML":


  • Posts are HTML formatted. Put <p> </p> tags around your paragraphs. Put <code> </code> tags around your code and data!
  • Titles consisting of a single word are discouraged, and in most cases are disallowed outright.
  • Read Where should I post X? if you're not absolutely sure you're posting in the right place.
  • Please read these before you post! —
  • Posts may use any of the Perl Monks Approved HTML tags:
    a, abbr, b, big, blockquote, br, caption, center, col, colgroup, dd, del, details, div, dl, dt, em, font, h1, h2, h3, h4, h5, h6, hr, i, ins, li, ol, p, pre, readmore, small, span, spoiler, strike, strong, sub, summary, sup, table, tbody, td, tfoot, th, thead, tr, tt, u, ul, wbr
  • You may need to use entities for some characters, as follows. (Exception: Within code tags, you can put the characters literally.)
            For:     Use:
    & &amp;
    < &lt;
    > &gt;
    [ &#91;
    ] &#93;
  • Link using PerlMonks shortcuts! What shortcuts can I use for linking?
  • See Writeup Formatting Tips and other pages linked from there for more info.