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.

Design documents question

In the company I am working, we are developing custom-made, client-server applications(sometimes with web support).  Platform and programming languages vary from project to project, but we are basically into OO languages like C++/JAVA/C#.  Project schedules vary from 3 months to 1-2 years.  The process model we are using is waterfall.  My question is, if you are also into this similar development, what kind of design documents--like (some/all of) UML diagrams, UI documets,etc.--do you create/suggest and what tools do you use/suggest?
jhanx Send private email
Wednesday, March 14, 2007
1.  Scott Ambler, "Agile Modeling".  Tries to reduce the UML forest into the useful trees.

2.  Ambler and Constantine, "The Unified Process".
Wednesday, March 14, 2007

I've just released an online book about an improved UML syntax I've invented. . I call them "Software Circuits", as the notation is so much simpler than UML's that, at least to me, it looks like you are wiring up the software.

The really cool thing is that the visual notation corresponds in a one-to-one manner with code mechanisms.  The #1 frustration I had with UML was how imprecise it was.  I fixed that with a few innovations that *greatly* simplify the generated code.

So if you go to the effort of documenting the code with a  Software Circuit diagram, there is proposed code "mechanism" or implementation to go right along with it. The code mechanisms are also designed to be completely language neutral and will port to all of the commonly used OO languages.

I'm also going to be releasing a free editing tool in the not-to-distant future to make all this much easier, but I'm hoping people will want to dig into the concepts as well and get a good grasp on a new way to *really* visually program.

There are tons of other benefits all my marketing hype goes into.  Please take a look and give me some feedback!.
Mark Truluck Send private email
Wednesday, March 14, 2007
> The process model we are using is waterfall.

It's kind of amazing to me that people still say this.  It's shorthand for "the process model we are using is the one that people who don't know what they're doing use, the one that's been identified as a key source of risks and failures since it was first described in 1970."  (See for Winston Royce's 1970 paper "Managing The Development of Large Software Systems.")

To this day, there are people who don't recognize that "we use the waterfall model" practically means "we don't know how to develop software."
Robert Rossney Send private email
Wednesday, March 14, 2007
From the perspective of the original poster's company, what constitutes a design document?

We complete similar types of projects, ranging from a week to a year in duration, but we rarely work in teams larger than two or three people. When you have three developers withing shouting distance of each other, meeting daily, and other stakeholders a phone call away, producing UML diagrams is a bit overkill.

I'm not saying they're not useful, but documentation of any type, particularly requirements and design, are really a way to formalize agreement upon what actually has to be done. For a team as small as ours, a list upon a whiteboard is sufficient. For a 30 man team, with several influential and political "sponsors", you definitely do want something in writing to protect yourselves.
Wednesday, March 14, 2007
+1 Robert

I'm always amazed at people who sneer at agile by saying "we're not hackers, we use waterfall".  The jury may still be out on agile, but waterfall has been shown NOT to work in numerous empirical sudies.
Mike S Send private email
Wednesday, March 14, 2007
Big, long waterfall projects don't work.  Shorter waterfall cycles work very well.  Spec/design/code/build/repeat.
Wednesday, March 14, 2007
> cogiton ... Please take a look and give me some feedback!

You might be interested in LabView.

> corresponds in a one-to-one manner with code mechanisms

If I want code-level detail then I can look at the code; perhaps a reason why UML is useful is because it shows a higher-level view than the code.
Christopher Wells Send private email
Wednesday, March 14, 2007
"Shorter waterfall cycles"

An interesting point.  You still need to get requirements, design, implement, test, deploy, support, repeat.  All the various methodologies seem to boil down to how much time is spent on these components and how much is done in parallel vs serial.  They also pin down either Time, Functionality, or Resources.

It all seems to spring from the same thing.  Ultimately it is fruitless to produce something for which there is no defined problem.

What the more 'modern' methodologies seem to indicate is that it is pointless to plan too far into the future, although you can also design for flexibility provided it doesn't cost too much in the short term.

Long term waterfalls don't have that flexibility to handle rapidly changing requirements.  Shorter waterfalls can work fine as long as people understand a changed requirement might not make the current release, and that software evolves, it is never perfect on any given release.
Dan Fleet Send private email
Wednesday, March 14, 2007
<It's kind of amazing to me that people still say this.>

Our project cycle is something like this:
1) Sales people find projects for us
-during this stage, initial project schedule is set,
basic requirements are identified.  There might be several others trying to outbid us to get this project.
2) Project is given to the dev team
3) Dev team starts with the basic design
-customer requirements are further discussed
-basic design documents(System deployment configuration, GUI specifications, etc) are presented to the customer, etc, until agreements are reached
4) Dev team proceeds to the next level of design
-these are the "Design documents" that I am asking
-These design documents are basically for the dev team's use during the coding phase
5) Dev team performs testing
6) Release and Maintenance

There might be some change of and/or additional requirements along the way in any phase, so we go back to #3 above for that particular change. Sometimes schedule is changed, most of the times not. So, what do you think would be the best process model that we should use?

The 4 projects I'm involved with for the past 4 years are all replacements of some 20year-old legacy systems.
Continuous operation is very important for the customer.
They can't even afford to have a 30-minute downtime during the installation. So far I never had encountered fatal software failures, project delay, and overbudget.

<From the perspective of the original poster's company, what constitutes a design document?>

What I meant of design document here is something like a blueprint when an engineer builds a building.  We use these design documents as a basis for coding, code reviews, and test specs creation/review.
The whole project team could range from 20 to 50 members.  Then it is still further subdivided into subgroups of 5 to 15 members.  These subgroups work independently.  We get to interact with other subgroups only during the testing phase(IT phase).
jhanx Send private email
Wednesday, March 14, 2007
The design documents depend on what you need (and, on who "you" are: different people want different 'views').

The preface to _Documenting Software Architectures: Views and Beyond_ says,

    "How would you "document" a bird's wing for someone who did not know what it was? A bird's wing, like a software system, can be shown by emphasizing any number of structures -- feathers, skeleton, circulatory system, musculature: each structure must be compatible with the others and work torwards fulfilling a common purpose. The feathers, for example, are ..."

The highest-level system analysis/design diagram (not to mention use case diagrams) that I like is a Data Flow Diagram (which predates UML).

If you're doing waterfall I personally like to see end-user documentation a.s.a.p., because that defines the system's external interfaces: the UI (in the user manual), the system components (in the installation manual), logs and so on (in the operations manual and administrator's guide).

I wouldn't mind API documentation too if there's an API, and/or a protocol definition if there's a network protocol or similar in there somewhere.

Event/state definitions are highly useful too, if you can model those, if it's anything like a complicated event-driven finite state machine.

For UML diagrams I've enjoyed using Enterprise Architect (more than I've enjoyed some other UML tools), but I don't know whether you need those.

It's an interesting topic.
Christopher Wells Send private email
Wednesday, March 14, 2007
What documents do your team need?

Do not create documents just because someone on a web site (or in a book) says to.  Do not skip documents for similar reasons.  Instead, decide based on criteria like:

* What does the contract require?
* What do we need to keep developers from tripping over each other?
* What do we need when we have to go back and fix something?
* What do we need to maintain a CMMI/ISO/ITIL/whatever rating?

You are really in the best position to answer the design documents question for your own team.
Wayne M.
Thursday, March 15, 2007
For UI Design documentation, I have had excellant results using Axure RP Pro
MT Heart
Thursday, March 22, 2007

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

Other recent topics Other recent topics
Powered by FogBugz