Prev: Threadpool 1.14 ...
Next: [ANN] Agile + Software Testing & Quality in Methods & Tools Spring 2010
From: AG on 24 Mar 2010 11:31
Hey all,

I am curious if someone could point me to an example "design
document." See the below quote for context:

"Create a design document to include DB, application, interfaces,
etc. with estimates."

Anyone have an example which includes DB, application, interfaces,
with estimates? I've made data-flow diagrams, data dictionaries,
flowcharts, etc before, but nothing so comprehensive. I'm a tad
confused as to where to start. I need a template.

Thanks!
From: Richard Heathfield on 28 Mar 2010 18:23
AG wrote:
> Hey all,
>
> I am curious if someone could point me to an example "design
> document." See the below quote for context:
>
> "Create a design document to include DB, application, interfaces,
> etc. with estimates."
>
> Anyone have an example which includes DB, application, interfaces,
> with estimates? I've made data-flow diagrams, data dictionaries,
> flowcharts, etc before, but nothing so comprehensive. I'm a tad
> confused as to where to start. I need a template.
>
> Thanks!

Nobody seems to have taken you up on this. I think that may be because
good design documents vary too much to be tied down to a template. The
design document for a word processor will be very, very, very different
to the design document for a nuclear reactor emergency shutdown program.

But really, the clue is in the question. You have quite a lot to go on
already.

[This response is based on the view that design and construction are
different steps in the SDLC, and that the design document will be handed
to a programmer or team thereof, for the purpose of writing the program.
This is not the only SDLC model or even necessarily the best, but I am
guessing it is still the model most often taught in universities.]

Note that the purpose of a design document is to document the design.
Therefore, the first step is to design the program. Your input into this
process is the requirements specification, which is the outpouring of
your software analyst's wisdom, often (but not always) based on his or
her cosy little chats with the customer.

Once you've got a design that you reckon meets the requirements, you are
in a position to document it.

Start off by deciding which aspects of the program design you need to
document. The list you are given is really there to help you get
started: "database, application, interfaces, etc with estimates"
suggests that you are being asked to design a layered application, quite
possibly (re-)using existing project code. The killer is "etc" - what
goes in there will very much depend on your tutor's perspective, so
think back to your lectures and previous practicals - what do you think
he or she is looking for? Possibly a section on error handling and
reporting, or perhaps internationalisation, or maybe formatting options,
or screen layouts, or customised networking protocols - or indeed all of
the above.

Once you've decided which aspects of the design to document, you've got
your outline. Now you just have to fill it in.

For example, documenting your database design is easy. It's doing the
design in the first place that's hard! But to document it, all you have
to do is say what database model you're using (flat, hierarchical, RDBMS
or whatever), and then list your tables, their record structures, the
purpose of each table in general and each field in particular, and the
relationships between records. If you do that in sufficient detail for
anything much larger than "hello world", you're almost bound to get an
A, because the lecturer will find little or nothing to mark down, and
will have fallen asleep long before he gets to the end of that section
and onto the next.

Anyway, moving on: documenting the application is just a matter of
saying what the program's supposed to do and outlining a design that
will achieve that objective. Depending on the application, this is
almost a trivial step, given the database design. Fred Brooks liked to
quote a guy who once observed that a peek at the code is unenlightening
(wrt program functionality), but a peek at the tables (data) renders a
peek at the code unnecessary.

To document the interfaces, you need to know what interfaces to what. If
you're using a layered model, you probably have a business logic layer,
a presentation layer, and a database layer. Underlying all of them you
almost certainly have a library layer, where you've got a bunch of
re-usable code into which any or all of them might need to tap. An
interface is any point at which one layer needs to be in contact with
another layer (e.g. if you've got a bunch of graphics notquiteprimitives
in the library and your presentation layer needs to call them, that's an
interface right there) - but you'll probably want to keep your
description at a relatively high level at this point - it is not the
purpose of the design document to put arbitrary constraints on the
creativity and intelligence of the programmer.

As well as documenting internal interfaces, you will want to document
external interfaces - file formats, network conversation frameworks, and
user I/O (screen, keyboard, command-line options, and (for a GUI-based
program) maybe menu layout and dialog box suggestions.

If you do all of the above, diligently and thoroughly, you probably
won't need to worry about including more than, say, one layer of "etc".
Error handling is always a good one.

Punctuate with liberal amounts of figures, diagrams, and charts
(projected data storage requirements, layer diagram, data model, the
whole nine yards). Top and tail with contents, introduction, and index.
Stick your name on the top, and I think you're more or less done.

Others here will, no doubt, point out any obvious omissions in the above.

--
Richard Heathfield <http://www.cpax.org.uk>
Email: -http://www. +rjh@
"Usenet is a strange place" - dmr 29 July 1999
Sig line vacant - apply within
 | 
Pages: 1
Prev: Threadpool 1.14 ...
Next: [ANN] Agile + Software Testing & Quality in Methods & Tools Spring 2010