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.

Software Design Documents

Do you guys develop your own software design documents or do you use some sort of package? I am trying to come up with a good set of documents I can use for some of my project ideas.

My current employer doesn't use them and the documents I developed in college aren't exactly what I am looking for.

Thanks for your help!
Ben Send private email
Wednesday, June 01, 2005
Right now, we're looking at something called DOORS for our requirements gathering piece.  It's very versitile, but also pricey.
Up to now, we've been using good ole' MS Word and Excel.
Wednesday, June 01, 2005
Wednesday, June 01, 2005
We use Word documents and use a project/release tracking tool (our own) for the individual features, etc.

The most important question to ask is "who is your audience?".  There are many kinds of documents you could produce, but the level and content should target the right audience.

Some ideas for a new project:

- Concept document (aka Product requirements doc, usually targeted towards someone non-technical or marketing oriented.  Explain what the business problem or market need is, and how your approach will satisfy it.

- Functional specification: This document describes how your product will work.  You can include usage scenarios, and either wireframes or mockups of the screens.  Look in Joel's archive for "painless functional specs" for some ideas on this one.

- (Optional) Technical spec/detailed design document: Targeted towards developers to follow (or outsourcers) - this would cover the architecture of the system, database schema if applicable, major modules of the system and how they interact.

There's no one-size-fits-all with these, and the level of detail will depend on the type of project (e.g. don't write a novel for a simple utility).  Also remember that people don't read.  Really, they don't.  If you can put something in a 2 page summary, then do so, with additional detail or reference in later sections.  And lots of screenshots, lists, and tables.

Good luck.
Dave C
Wednesday, June 01, 2005

Wednesday, June 01, 2005
If you find yourself writing your own documentation I recommend gleaning some information from this site:
Boxes and Arrows
Tuesday, June 07, 2005
We've been using DOORS at work for a couple of years now and it's still giving us many problems. Telelogic doesn't respond quickly to support issues (i.e. the time between when a bug is found and when it is fixed is glacial). Also the design of the application has caused trouble for many folks who use it. Each 'row' in the document is a unique object, stored in a DB, which can be tagged with different feature/product/release information and can be linked to/from other objects (to meet traceability requirements). Before using DOORS, you really need to have a team (made up of the folks who write the requirements, implement the requirements and test the requirements) sit down and agree upon the organization of the requirements -- otherwise you'll get folks duplicating requirements, accidentally deleting requirements or destructively modifying requirements (i.e. removing/replacing tags from old releases).

I guess, as with any tool, you'll need to be careful how it is used. Setting up guidelines for use and training your team in its use is definitely recommended.
Sean Mountcastle Send private email
Monday, June 13, 2005

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

Other recent topics Other recent topics
Powered by FogBugz