views:

1072

answers:

6

In the course of your software development lifecycle, what essential design artifacts do you produce? What makes them essential to your practice?

The project I'm currently on has been in production for 8+ years. This web application has been actively enhanced and maintained over that time. While we have CMMI based policies and processes in place, with portions of our practice being well defined, the design phase has been largely overlooked. Best practices, anyone?

+4  A: 

Working code...and whiteboard drawings.

:P

Jason Bunting
+1  A: 

Designs change so much during development and afterwards that most of my carefully crafted documents rot away in source control and become almost more of a hindrance than a help, once code is in production. I see design documents as necessary to good communication and to clarify your thinking while you develop something, but after that it takes a herculean effort to keep them properly maintained.

I do take pictures of whiteboards and save the JPEGs to source control. Those are some of my best design docs!

Eric Z Beard
+1  A: 

In our model (which is fairly specific to business process applications) the design artefacts include:

  • a domain data model, with comments on each entity and attribute
  • a properties file listing all the modify and create triggers on each entity, calculated attributes, validators and other business logic
  • a set of screen definitions (view model)

However do these really count as design artefacts? Our framework is such that these definitions are used to generate the actual code of the system, so maybe they go beyond design.

But the fact that they serve double duty is powerful because they are, by definition, up to date and synchronised with the code at all times.

Leigh Caldwell
+3  A: 

Having worked on a lot of waterfall projects in the past and a lot of adhoc and agile projects more recently, there's a number of design artifacts I like to create although I can't state enough that it really depends on the details of the project (methodology/team structure/timescale/tools etc).

For a generic, server-based 'enterprise application' I'd want the bare minimum to be something along these lines:

  • A detailed functional design document (aka spec). Generally something along the lines of Joel s' WhatsTimeIsIt example spec, although probably with some UML use-case diagrams.
  • A software techical design document. Not necessarily detailed for 100% system coverage but detailed in all the key areas and containing all the design decisions. Being a bit of an UML freak it'd be nice to see lots of pictures along the lines of package diagrams, component diagrams, key feature class diagrams, and probably some sequence diagrams thrown in for good measure.
  • An infrastructure design document. Probably with UML deployment diagram for the conceptual deisng and perhaps a network diagram for something more physical.

When I say document any of the above might be broken down into multiple documents, or perhaps stored on a wiki/some other tool.

As for their usefulness, my philosophy has always been that a development team should always be able to hand over an application to a support team without having to hand over their phone numbers. If the design artifacts don't clealry indicate what the application does, how it does it, and where it does it then you know the support team are going to give the app the same care and attention they would a rabid dog.

I should mention I'm not vindicating the practice of handing software over from a dev team to a support team once it's finished, which raises all manner of interesting issues, I'm just saying it should be possible if the management so desired.

Ubiguchi
+1  A: 

This is not a design document, per se, but our unit tests serve the dual purpose of "describing" how the code they test is supposed to function. The nice part about this is that they never get out of date, since our unit tests must pass for our build to succeed.

Matt Dillard
A: 

I don't think anything can take the place of a good old fashioned design spec for the following reasons:

  • It serves as a means of communicating how you will build an application to others.
  • It lets you get ideas out of your head so you don't worry about tracking a million things at the same time.
  • If you have to pause a project and return to it later you're not starting your thought process over again.

I like to see various bits of info in a design spec:

  • General explanation of your approach to the challenge at hand
  • How will you monitor your application?
  • What are the security concerns and how are they addressed?
  • Flowcharts / sequence diagrams
  • Open issues
  • Known limitations

Unit tests, while a fantastic and arguably critical item to include in your application development, don't cover all of these topics.

Ian Suttle