The Design of Software (CLOSED)

A public forum for discussing the design of software, from the user interface to the code architecture. Now closed.

The "Design of Software" discussion group has been merged with the main Joel on Software discussion group.

The archives will remain online indefinitely.

What makes a good technical design?

Until very recently, I thought I was the only one who didn't really know what to put into a technical desing to make it "good" and "complete."
But I have searched at length for a "good" technical design, and have come up empty.  In talking with my peers, who are for the most part developers, we realize that there are MANY different ideas about what a good technical design includes.
To me, it is like a recipe:  It has pictures of what the finished product will look like.  It has a list of functionality to be included.  It has instructions on the order of which to build the functionality.  It includes test cases to make sure a user who enjoys breaking things, can't.
But one thing is truly missing in my search:  A template.
I have yet to find a good template for a technical design for a software application.

Has anyone else seen one?
(I mean a "good" one.)
LJ Send private email
Wednesday, December 14, 2005
That it does everything it needs to and nothing it doesn't.

KC Send private email
Wednesday, December 14, 2005
I suspect that "a good technical design" document depends on the domain you are in (Nasa Satellite Telemetry capture is very different from IRS Web-Page Design, which is different from Boston Big-Dig Highway control).

In addition, each customer is different and wants to see different things.  It's kind of like asking for a template for a plan for a building.  What kind?  Skyscraper, Performing Hall, 2000 Square Foot Residential?

And then you have our rapidly evolving technology base.  What language?  What GUI features?  Is it OOD, or DFD?  Is it SEI CMM, CMM-I, level 2, 3, 4, or 5?  Is it web-based? Swing? Linux? Windows?

In theory, none of these considerations make a difference, as they can all be considered "implementation details".  In practice, each platform and language you consider makes some parts of the design easy, others harder.

Even so, you might think there are SOME specifications.  DOD 2167 had a couple of major documents -- a description of multiple product documents, and a "Tailoring Guide" for producing them.  Now 2167 is out of favor, I understand.
Wednesday, December 14, 2005
+1 to AllenL5.

Keep in mind that a technical design (document) is good IF it answers the all of the audience's questions AND does not raise additional, unanswered questions AND does not provide more detail than is needed.

"Audience" however is a variable.  Audience can include in one group, an experienced superstar programmer, a poor  programmer fresh out of college, and a bean counting manager.  Creating a good technical design document that satisfies all three extremes is more black magic than science.

(I know of projects that tailor separate design documents to address different groups of people.)

At best, all you can hope for with a template is that it will be a list of all the different things the author thinks you should talk about.  It's extremely rare that list will be 100% compatible with your audience; you will have to do some customization.
Anonymous Coward
Wednesday, December 14, 2005
In the interest of providing some positive, constructive suggestions, I basically read books on software project management and compare the scenarios in those books with the circumstances in my organization.

For example, most of the users in my current organization will have a specific problem I can solve, but generally don't care how the problem is solved (they're willing to put up with bad interfaces for example).

Consequently, I tend not to write a technical design, but instead focus on a functional spec and lots of change control documents to track how features are implemented, tested, and accepted or rejected (and why).  Coincidently, the cumulative stack of change control documents has proven to be the best "technical specifications/design" document I could possibly ever create in this situation because everything is documented in chronological order and developers can easily see when and why something was added.

The downside is that we also put out monthly maintenance releases - which is good for the customer because they can provide immediate feedback.  This would not be a good solution if you're producing shrink-wrapped software with a yearly release cycle.
Anonymous Coward
Wednesday, December 14, 2005
It's a good design if the thing you design is used in the future in a way that the original developer never anticipated, and it works correctly with no modification.
cbmc64 Send private email
Thursday, December 15, 2005
One of my previous mentors used to repeat this mantra.

* A good functional spec must capture the requirements fully, and must be designed in such a way that it can translate to a design doc smoothly.
* A good design spec must capture the functional spec fully and must yield to a good test plan.
* Both the above steps are iterative, with feedback at every stage of development.

I found these very pragmatic and insightful.
It can't be... but I could be wrong Send private email
Thursday, December 15, 2005

This topic is archived. No further replies will be accepted.

Other recent topics Other recent topics
Powered by FogBugz