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.

Lazy-man software design document


I want to find some examples of software design document that is minimal but effective in describing a software design, and at the same time, without lengthy details like those mentioned in full UML specification.

If you come across one or two of such an example documents, please let me know and would appreciate your help.

Paul Sutton Send private email
Saturday, March 26, 2005
Yes, we were able to generate such a beast.

Input:  A Requirements Document


Preliminary Design -- A Context diagram of the top level.  Next a DFD of the next level down, showing the entities that needed to be created.  Next level down, a Class diagram, showing how the entities would inter-relate.

Detailed Design -- a fleshing out of the Class diagram (Adding methods and properties), and a Sequence Diagram showing how the methods would relate to each other.

A preliminary set of software code that showed the Detailed Design was implementable.

A Set of 'derived requirements' that became obvious during the detailed design process.

A Set of 'assumptions' that had to be made to make progress, that then would need further verification with the customer.
Saturday, March 26, 2005
Or, if you want to be really lazy, you can skip the design doc altogther.

Before I start a major project, I send an email to my manager and a couple of the brighter programmers, casually explaining my plans. We can then have an email or face-to-face discussion that takes everyone's views into account. If my email might be helpful later on, I'll copy it onto our Wiki.

At least for a small company, that approach works just fine. If someone has questions after the code has been written, I can present a whiteboard explanation easily enough.
Saturday, March 26, 2005
"If someone has questions after the code has been written, I can present a whiteboard explanation easily enough. "

That's a pretty tough trick to pull off once you've left the company...  ;)
Saturday, March 26, 2005
"Before I start a major project, I send an email to my manager and a couple of the brighter programmers, casually explaining my plans. "

And at what point does someone who will actually be using the system get to sign of on your ideas? Or do only programmers get a say in the final product?  ;)

Sorry, I don't mean to flame you. I've actually seen your way work much better than the formalized spec approach. There ought to be some middle ground that would be more desirable and produce better results but I have yet to ever really find it. The usual problem is a lack of competance or product understanding on the part of the people writing the specs.
Saturday, March 26, 2005
Paul Sutton writes:

"I want to find some examples of software design document that is minimal but effective in describing a software design, and at the same time, without lengthy details..."

Okay, my first question for you -- for HOW large of a project?

The reason I ask is, let's say you wanted something like a small desktop app.  For example, a CD Ripper.  Well, you could probably get away with telling a programmer, "it has to rip files from a CD".  Maybe also "And it should convert files to MP3".  That would be really enough for a reasonably good programmer to create such an app for you.  But, how do you want the UI to look?  Do you want any custom kinds of things?  Are there any potentially unsafe interactions between features and data?

For a HUGE Fortune 100 project, yes, you'll probably need something of a spec.  Depends on the programmer(s) also.  Will the programmer(s) consider things which can "go wrong" within an app written for a particular problem domain, or will he or she blindly (or out of pure ignorance) ignore them?  Will you know ahead of time?

Will this be a single programmer project or team project?  If a team, you'll definitely need a spec.  Who will be responsible for what on the team?  And so it goes.

Also, let's reverse the question.  Let's say I was your boss, and you were to get your project done the way you wanted it.  But I hand you one constraint.  Your spec must be as minimal as possible, ideally non-existent, but if there's something important, something that wouldn't be *obvious* to a person of reasonable intelligence, then and *only* then will you be able to put that on the spec.  Also, I want you to write a list of *anything* you think might be missing from your spec.

From that point, you *should* be able to take those documents to a qualified developer, and be able to discuss further enhancements/modifications to the spec.

Well, I don't know if I've totally confused you, but the scope of the project and how many programmers are to accomplish it can play a large role in determining the size of a spec, as can application complexity.

Well, wishing you luck!  Hopefully it helped, and if it didn't -- feel free to ignore my post! ;)

Peter Sherman Send private email
Saturday, March 26, 2005
In response to what others have said...

In my experience, after someone leaves the company, their source code is more informative than the design docs they left behind.

Design docs have value, but writing them doesn't seem to be the best use of my time. Casual email and whiteboard sessions are much more efficient means of communication.

I do write reference manuals, which describe the architecure components, installation procedure, configuration parameters, etc. However, I wrote those docs after the completing the code, rather than before.

To gather requirements, I talk to people in Client Services, who in turn speak to the customer. However Client Services isn't technical enough to follow our design discussions. Instead, they provide feedback after Engineering prepares a working version.

Obviously, circumstances are different in other companies.
Saturday, March 26, 2005
Firstly, thank you for all your inputs

Let me provide more information as someone was asking about this. I am not going to write a simple snippet that involves not more than 2 people. My targeted applications  will consist about 20-40 components and about 5000-10000 lines of code. We need to maintain and reuse the components so carefully design of its responsibilities and interfaces are required. Customization on the software to suit different customers, at least on UI, is also an requirement.

This project will initially involve 5-10 programmers, and would be more when involving customization stage to different customers.

So, even I am not a strong believer of specs and docs, I still believe the minimal documentation would be useful for this type of projects. Sometime like Context diagram, Class diagram, State diagram, Class definition, or even cover the Class implementation.

So, I am asking for the community about an example so that  I could just follow the format and the depth of presentation from someone who did a similar job and found it adequate and useful.

Thanks for your reading and replies again,

Paul Sutton Send private email
Saturday, March 26, 2005
Confucius said, "A fanatic is one who redoubles his efforts while losing sight of his goal."  In light of that, here's my approach to documentation: the purpose of a doc is for any reasonably intelligent person to read it & see right away (a) what the thing does, and (b) how it does it. I use any means necessary to get to that goal, including, but not limited to, bubble (aka data flow) diagrams, scanned hand-drawn cartoons & pictures, explanations, FAQs and Q&As. Don't let the tools (UML or Micrisoft Word) get in your way--keep your eyes on the prize: comprehensibility. If powerpoint is hobbling you, don't use it, use a pen and a scanner. Don't use that snooty official tone that nobody can understand. Keep it simple, simple, simple. Nobody to date has ever complained about not being able to understand something I've written.
John Foxx
Sunday, March 27, 2005
Firdaus Send private email
Sunday, March 27, 2005
Before design comes function... First, it's important to know what you are designing.
After that has been well defined (and hopefully signed off by the eventual users) comes a design spec. 
This document should represent a thought out process of meeting the functional needs. This is usually as valuable in assisting the developer in organizing his thoughts as informing others. If there are more than one developer on the project, this will also define what each portion of the project is responsible for and how it will interact with other portions. In this fashion, each participant will know what the part they are working on actually is expected to do.
Then, before starting coding, the design should be compared to the functional requirements to ensure that they are being met.
Lastly this functional requirements doc and design doc should accurately communicate what the project is all about. They should also allow the process to go forward for the crew that is testing the resultant code (system) to see if the requirements are met.
How "Official" one gets with this documentation is up to the organization. a small well knit team obviously can accomplish great things with less documentation but as demands increase and the size of the project and or team grows, the documentation becomes increasingly more important.
These decisions also hinge around how the resultant code will be supported going forward.
There are many differnt templates out there. Some good others not so. All serve to provoke thought about the process.
A well done design document should allow the author to pass off the development to others with little or no further input.
Mike Spangler Send private email
Wednesday, April 20, 2005

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

Other recent topics Other recent topics
Powered by FogBugz