Welcome to the Slashdot Beta site -- learn more here. Use the link in the footer or click here to return to the Classic version of Slashdot.

Thank you!

Before you choose to head back to the Classic look of the site, we'd appreciate it if you share your thoughts on the Beta; your feedback is what drives our ongoing development.

Beta is different and we value you taking the time to try it out. Please take a look at the changes we've made in Beta and  learn more about it. Thanks for reading, and for making the site better!

What Makes a Good Design Document?

Cliff posted more than 9 years ago | from the techincal-writing dept.

Communications 461

dnnrly asks: "I've been writing software professionaly for a couple of years now for more than 1 company and I've noticed a recurring pattern: I get put on a new project that already has a bit of history and I get told to read the design documents and then implement XYZ. What happens is I read the document, find that it gives me a lot of information about certain aspects of the system we are building, but leaves huge gaps in others. We're going to be rewriting some of the procedures very soon and I'll be able to influence the software side so I wanted to ask Slashdot readers what sort of things have they seen in design documents that they've liked/thought are a good idea? What have they found works and what doesn't? If all else fails, where's a good place to find all this stuff out?""There's usually a very defined and rigid format for every design document and the writers have obviously tried very hard to make sure that procedure has been followed, generally leading to an almost unreadable doc or a design for the sake of it. Part of the issue is that these guys have written the design after 2 or more years exposure to the problem so they tend to forget just how much they know."

cancel ×


Sorry! There are no comments related to the filter you selected.

FP (-1, Troll)

Anonymous Coward | more than 9 years ago | (#12270361)

first post! arse!

Existence (2, Insightful)

Soskywalkr (617860) | more than 9 years ago | (#12270372)

As opposed to some napkin smudged with barbeque wings...

FP (-1, Offtopic)

Anonymous Coward | more than 9 years ago | (#12270376)

frist psot?

"What is software design?" (5, Informative)

tcopeland (32225) | more than 9 years ago | (#12270384)

Here's the classic article [] by Jack Reeves.

Design Document (5, Funny)

goretexguy (619280) | more than 9 years ago | (#12270386)


Duh (4, Insightful)

Erwos (553607) | more than 9 years ago | (#12270405)

Figure out which class from your local university deals with software engineering, find the book(s) for the class, and buy it.

Writing a good design doc is mostly tedious work interspersed with lots and lots of communication with your programmers and customer.


Re:Duh (2, Interesting)

OhPlz (168413) | more than 9 years ago | (#12270470)

I'm still taking CS classes after ten years in the business. The books my college uses present an assortment of different design techniques and various documents that go along with them. They do not present an absolute solution.

I dare say that I haven't seen much in the way of design documents in anything I do. A "design" to me, typically means a braindump committed to email. It's not too surprising either, I doubt many software engineers got into the business to write documents.

Re:Duh (0, Funny)

Anonymous Coward | more than 9 years ago | (#12270558)

If you still haven't gotten a CS degree after 10 years, maybe its time to look into another career path.

Just sayin'.

Re:Duh (5, Insightful)

JackAtCepstral (870238) | more than 9 years ago | (#12270563)

"I doubt many software engineers got into the business to write documents."

No, that's just it. People often ask the difference between a Software Engineer and a Computer Scientist. This pretty well covers it. Ideally, a Software Engineer is an Engineer like any other. A major portion of their work is designing and documenting. Like how a Structural Engineer would create blueprints. Also ideally, a Computer Scientist is a scientist like any other. He investigates the world of computer software - experimenting and recordign the results.

In the real world, the roles of both blurr into "the customer wants this, code it." But to live up to the title of Software Engineer, you need to be much more proactive and be very involved in the non-programming aspects such as requirements gathering, documenting, designing, documenting, prototyping, documenting, and documenting.

Re:Duh (5, Interesting)

EEBaum (520514) | more than 9 years ago | (#12270492)

Figure out which class from your local university deals with software engineering, find the book(s) for the class, and buy it.

Then burn it. The methods are all nice in theory, but in practice it's often a crapshoot. Then again, I have a bit of history on this one, as my software engineering class was more of a class on how to deal with the PHB (clueless professor).

We learned how to make all the pretty diagrams, while we discovered that such pretty diagrams could never have relevance to our particular project. It ended up a game of "make the diagrams the customer wants, then make much simpler and more sensible ones for yourself that don't follow proper software engineering protocol but actually tell us how the darn thing works."

Re:Duh (2, Insightful)

smitty_one_each (243267) | more than 9 years ago | (#12270745)

C2 [] lays it out.
School is about learning the terminology and trying to get the most egregious errors out of the way, so that, after graduation, real work can commence.

About Resources (1)

superpulpsicle (533373) | more than 9 years ago | (#12270408)

The person writing the document should have enough software/hardware resources. So many engineering specs are written too early in the phase when there is nothing tangible. It just becomes a fairy tale document.

A good design document... (-1, Offtopic)

IANAAC (692242) | more than 9 years ago | (#12270409)

properly matches the icon with the title.

The problem. (2, Funny)

ShaniaTwain (197446) | more than 9 years ago | (#12270410)

Part of the issue is that these guys have written the design after 2 or more years exposure to the problem so they tend to forget just how much they know.

why? is the problem radioactive? Some sort of alien compound that causes forgetfulness? Sounds potentially preferable to some of the projects I've worked on.

Mythical Creatures (4, Funny)

telecsan (170227) | more than 9 years ago | (#12270411)

The design document was rumored to be a cross between a unicorn and the dodo bird. What would a bird need with a big pointy horn on it's head? I don't know, but then, I've never seen one of these rumored documents, so I can't say for sure.

Re:Mythical Creatures? NOT (2, Insightful)

jcomeau_ictx (696704) | more than 9 years ago | (#12270576)

I don't know, but then, I've never seen one of these rumored documents, so I can't say for sure.
Sure, you have. RFCs are my idea of what makes a good design document: tell me what I have to do to make this software interoperable with the rest of the world, what you want this software to accomplish (including sample gozintas and gozoutas), and that's it. Short and sweet. Now get out of the way and let me code. :^)

RFCs are requirements documents, not design (5, Interesting)

rjh (40933) | more than 9 years ago | (#12270776)

RFCs are requirements documents, not design documents.

An RFC specifies what behavior MUST, MUST NOT, SHOULD, SHOULD NOT, MAY, MAY NOT exist. It doesn't say jack about how that behavior is supposed to come into being. I could write an OpenPGP application that did all of its work by hiring Bruce Schneier to manually do the RSA computations, and it'd pass the RFC.

RFCs aren't design documents. RFCs specify behavior; design documents specify how that behavior is achieved.

Re:Mythical Creatures (0, Offtopic)

GIL_Dude (850471) | more than 9 years ago | (#12270579)

I always thought the horn was to attact the virgins... Wait, maybe that was the other way around...

Be agile (2, Insightful)

kabdib (81955) | more than 9 years ago | (#12270412)

Who needs documentation? Just wade in with something like Scrum. Most documentation is out of date anyway (about a month after you're coding, it's useless).

Re:Be agile (1)

KlomDark (6370) | more than 9 years ago | (#12270519)

What? You mean the Tall Man from Phantasm? I guess that might work. (Here, you don't like that? Try a silver ball drilling a hole in your head...)

Oh wait, that was Angus Scrimm, not Angus Scrum.

I hate it when that happens (3, Insightful)

nietsch (112711) | more than 9 years ago | (#12270413)

This story has no posts, just when I tought it would be nice to read from others how they think about design problems.

All I can suggest is: keep a strict separation between features and implementation.
do some use cases that describe how the most important part (the user) will handle the program.

And think ahead, your designs will change while building/deploying. How are you going to accomodate that?

And tests, do not forget to write the tests! (3, Insightful)

nietsch (112711) | more than 9 years ago | (#12270502)

Write them before you write the new features, to test for the new features.

This will save you eons when you are actually coding. Way too many testers are still wasting their time with manually going through the ssame maotion again and again to make sure it all works as expected.

Don't use one (1, Interesting)

Anonymous Coward | more than 9 years ago | (#12270420)

Design documents are a waste of time. I have never seen one that is current, or even comes close to explaining the system accurately enough to be useful. The best solution is to write code that is easy to understand and go from there. Maybe create a high level diagram of the system, but let the code be the language in which the design is written. Do you really think the design document comes first? It never does. It is always done after the code is completed, and only because management has no clue and thinks documenting the system will make is easier to hire new developers. I'd honestly suggest looking at the design side of XP. I have used that a lot recently and have seen hug improvements in efficiency and code quality.

Re:Don't use one (0)

Anonymous Coward | more than 9 years ago | (#12270571)

I seriously hope you're not working on embedded systems...

Not doing design documents is a mortal sin.

Design Document requirements: (5, Insightful)

amichalo (132545) | more than 9 years ago | (#12270422)

Be sure your DD includes:
- Sitemap (web) or screen map (desktop app)
- Feature matrix with columns for features, rows for pages/screens and indicators where a page/screen has a feature.
- Detailed feature specs need to be written kinda like function documentation - "preconditions" that state what is expected as in the user is authenticated or the DB has products and "post conditions" that say what gets set or hwat the user can do.
- Style documents greated by graphics designers who understand the medium (web/Windows API/etc) are invaluable for refering back to when someone doesn't like a font size.

All this documenting is no fun, but it is more fun then dealing with the lake of the document.

Re:Design Document requirements: (1)

TechnologyX (743745) | more than 9 years ago | (#12270450)

"but it is more fun then dealing with the lake of the document."

But I bet that's better than dealing with the lake of fire anyday!

Re:Design Document requirements: (1)

VitaminB52 (550802) | more than 9 years ago | (#12270615)

Don't forget to include a terminology list.

Things like 'product price' tend to have a different meanings to different people (for sales people it's the selling price, for others the purchasing price; for some it's always the price + V.A.T., for others it's the price minus V.A.T., etc.).

Make sure everybody has the same mental picture when you talk about 'x' will help reducing the errors that creep into a project when 'x' has different meanings to different people.

Diagrams, for one thing (5, Insightful)

blueZ3 (744446) | more than 9 years ago | (#12270423)

I document software for end users, and get some of my information in the early stages of development from design docs. I have to say that the most useful design documents that I've seen are ones that contain diagrams, flowcharts, and other "pictures" of how the system (or the module, component, whatnot) functions.

If I have to choose between a 50-page design document and three pages of clear diagrams, I'd pick the pictures.

"pictures"? (0)

Anonymous Coward | more than 9 years ago | (#12270560)

>>If I have to choose between a 50-page design document and three pages of clear diagrams, I'd pick the pictures.

Bingo!! No stories, only porn pictures.

Pictures are good! (5, Interesting)

gosand (234100) | more than 9 years ago | (#12270669)

I have to say that the most useful design documents that I've seen are ones that contain diagrams, flowcharts, and other "pictures" of how the system (or the module, component, whatnot) functions.

Amen. I do Quality Assurance (and for those who don't know, that isn't just testing). I use design docs to figure out how something is supposed to work before I get it. Pictures are good. You can (intentionally) bury information in a 50 page document. It is hard to bury information in pictures. I say "intentionally" above because in the past I worked with a guy who was the director of a development group. He didn't like to design things, or tell people about how things were going to work. So his requirements and design documents were vast containers of information. His standard answer to questions was: It's in the document.

Me: What is the flow of events from beginning to end?
Him: It is in the document.
Me: I couldn't find it. Where is it?
Him: It's in there, you just have to find it. See, here on page 3, and on page 10, and...ummm... You just have to piece the information together, but it is all in there.

Talk about information hiding. In meetings, people would ask questions, and he would say "It's all in the document, should I go get it?" Nobody wanted to spend meeting time sifting through it for answers. And sometimes, the answers weren't there, and we would always get the "I'll add it". Of course, nobody ever checked to make sure he added it.

I fought for months to get him to add a flow diagram in a doc. He kept insisting that all the information was there and that a diagram was useless. After months and months, he finally added it. The FIRST thing that someone said at the next meeting was how useful that diagram was, and they pointed out some improvements to it. It turned out those comments sparked conversations that led to the discovery of flaws that went unnoticed for months. I'll leave it up to the reader to guess who got credit for the diagram in the document. (hint: Senior QA person or director of development)

Let me re-iterate: pictures are good.

Audience == People (3, Insightful)

mike_the_kid (58164) | more than 9 years ago | (#12270424)

Overly rigid structure and formatting are not helpful. Often times I think programmers are so used to writing for compilers that they forget that humans are much better parsers.

Design documents should be easilly written and easilly updated. I prefer a text editor to something where I can have 'really nice' formatting. Its just easier and quicker, and that leads to the documents being more likely to be kept up to date.

If the docs aren't up to date, no matter how well written or well designed they are, they are misleading and unhelpful.

Re:Audience == People (2, Insightful)

yagu (721525) | more than 9 years ago | (#12270704)

Unfortunately, templates and standards for design documents rarely are left to the hapless development staff but are instead left to the people who don't have to read them... Oh, they have to look at them, bind them, distribute them, and related "business" machinations, but they don't really have to READ them, and thus far too often technical teams are left having to shoehorn designs into inappropriate, rigid, and non sequitor documents. If this were an only-one-time experience in my career, I'd have more hope, but I've encountered this phenomenon over and over.

For the record, I agree: Design documents should be easilly written and easilly updated. I prefer a text editor to something where I can have 'really nice' formatting. Its just easier and quicker, and that leads to the documents being more likely to be kept up to date...., but ability and common sense about what documents SHOULD look like is far less likely to be the obstacle than the policy governing design documents.

Your mileage may vary. Good luck! We're counting on you.

Re:Audience == People (mod parent up) (1)

RealProgrammer (723725) | more than 9 years ago | (#12270742)

Every document should focus on its audience, which in the case of a design document changes over time. Its goal should be to get the reader up to speed on the target program or system, with as little self-aggrandizing fluff as possible. Keep it simple, and work from the top/outside to the bottom/inside.

It should always give an overview of the program, telling what each chunk does. It should also tell how the program does what it does in terms of the chunks of the program, but not the details of how each chunk should do what it does. It should tell how the chunks relate to accompish the task.

At first, the design document should specify the boundaries of each chunk of the program or system being developed, along with the data to be exchanged at the borders.

As time goes on, and the work progresses, the design document should be changed to reflect the current status, as if there were no work completed. The goal is to zero in on the completed program, not to have it expand out of control, so you have to watch that.

When handled properly, the finished program and the finished design document make a better finished product. When handled incorrectly, you have either unimplemented or undocumented features, two classes of bugs that are particularly annoying for the end user.

What's the purpose of the design doc? (4, Interesting)

DanielMarkham (765899) | more than 9 years ago | (#12270431)

Basic communications 101 says the purpose of any document is to communicate. And you, the poor schmoe left with maintenance, is exactly the guy the design doc is supposed to be talking to. Now a lot of times businesses create documents just to "check off the boxes" in which case they want some big, heavy monstrosity to deliver. If that's what you're getting, good luck. People (especially programmers) tend to think of design docs as some kind of ultimate bible in the sky that's going to answer all questions and be a completely accurate guide to what's in the code. That's fine in theory, but in the real world the best design doc you're going to find is one that tells you what the design team was thinking when they started down the path of building this program. What's the patterns that were used? What constraints kept them from doing things differently? It's just a technical memo from them to you that's supposed to help you get oriented and work more efficiently. Sometimes those memos aren't done so well. My advice is to get what general information you can from them, and then talk to the coders who worked on the project. That's my two cents.

a good place to find all this stuff (2, Insightful)

wiredog (43288) | more than 9 years ago | (#12270433)

The source, especially the comments. Assuming there are comments, and they don't read (I really saw this once) "Why did I do this?"

A good design document often duplicates the actual programming process. It starts at a high level (What are we trying to do? How do we do it?) and drills down to the level of what each function (or class method) should do. It should define acceptable inputs and outputs, both overall and for each method. It should also define the unacceptable ones. You should be able to generate the unit tests from it as well as the actual program.

It should leave room for changes if you find out that using methodology Bar to implement Foo doesn't work.

The Final Document should be based on a reading of the code, and any differences between that and the pre-code spec should be documented as to their cause.

Design documents become stale (3, Insightful)

davidwr (791652) | more than 9 years ago | (#12270435)

The biggest problem I've had with design documents is that they aren't updated.

When first written, they are good and complete.

As the project moves along and the design changes, the design documents aren't updated. If you are lucky, new features will be covered in errata documents, but old features that were found to be not feasable remain in the document, without any indication of why they were removed from the project.

A Big Chief Tablet and... (-1, Offtopic)

Anonymous Coward | more than 9 years ago | (#12270438)

... a box of Crayola crayons.

Re:A Big Chief Tablet and... (0)

dsplat (73054) | more than 9 years ago | (#12270596)

Spoken like an experienced Extreme Programmer [] .

Steps to writing a good design document (5, Funny)

GillBates0 (664202) | more than 9 years ago | (#12270440)

I've noticed a recurring pattern: I get put on a new project that already has a bit of history and I get told to read the design documents and then implement XYZ.

1. Write a design document containing information about the design document you're trying to create.
2. Read the design document you wrote in (1) describing the design document that you are trying to write.
3. Write actual design document as described in design document written in (2).

Re:Steps to writing a good design document (0)

88NoSoup4U88 (721233) | more than 9 years ago | (#12270503)

4. ?
5. Profit !

.... I'm sorry.

A Good Design Document (5, Informative)

darthtrevino (812116) | more than 9 years ago | (#12270448)

I've seen alot of design documents. Most of them fit into a sort of cookie-cutter as to what the company expects. If UML is standard, expect to see alot of crappy UML with substandard explanations.

The best design documents are ones that aren't trying as much to fit the cookie cutter as much as they clearly convey the idea of the design.

I'm not saying to throw design standards to the wind. I'm saying that your standard as a design document generator is to create something that is readable, decent to look at, and clearly conveys what is going on.

Try to use vernacular vocabulary and language style when explaining what things do, and try to make your pictures look as pleasing and simple as possible.

Hope that helps.

Re:A Good Design Document (5, Funny)

Anonymous Coward | more than 9 years ago | (#12270606)

Ironically, I had to look up "vernacular."

Interfaces (4, Insightful)

dsplat (73054) | more than 9 years ago | (#12270453)

There are lots of things that can, and arguably should, be documented in a design document. One category that should never be omitted is the interfaces. Whenever a system or subsystem interacts with something else, you need to know how. This includes:

  • Database schemas. Unless your DB is so well hidden that no one will ever find it, someone will want to read it some day.
  • APIs you support or use. If there's a standard or a 3rd party product, just list it and the version.
  • Command line parameters for those little maintenance tools you don't tell the users about. This is a design doc, not a users' guide.

You Already Know (2, Interesting)

4of12 (97621) | more than 9 years ago | (#12270455)

What happens is I read the document, find that it gives me a lot of information about certain aspects of the system we are building, but leaves huge gaps in others.

If you can already identify gaps in previous design documents, then you are already qualified to write the next design document.

Apart from that, talk to some other experienced people in your organization and get their take on previous projects failures and delays. Then, see if there is any way to preemptively incorporate measures into the design document to improve your projects chances for success.

[Although, a lot of project success really boils down to getting the right people on the team.]

Code (1)

Virtual Karma (862416) | more than 9 years ago | (#12270461)

I would still say that code is the best design. (these are not my word. I had read is somewhere and I forgot. Sorry about that, else I could have linked it). The article said that code is the best design document and shoudl be considered so. The actual 'construction' phase happen when the code is compiled by the compiler.

Keep it current (3, Insightful)

Reality Master 101 (179095) | more than 9 years ago | (#12270479)

There are a lot of things that can be said, but I think the biggest problem with design docs is that they aren't kept up-to-date.

If you're really serious about having useful design docs, the only way to do it is to have a dedicated staff whose job it is to keep it current, accurate and useful. Coders are rarely good writers, and even if they are, it's almost impossible to get them to keep docs in sync.

My favorite design document . . . (4, Insightful)

PIPBoy3000 (619296) | more than 9 years ago | (#12270493)

. . . is a prototype.

To be honest, I find that customers have a hard time visualizing how something will work unless they can interact with it. I'll take some internal design notes for myself, then whip up something and reiterate.

This approach doesn't work well with some projects, but for the small web applications I make it works great.

You have good intentions (1)

0kComputer (872064) | more than 9 years ago | (#12270494)

But sadly we are all part of the vicious cycle []

I know!!! (1)

Iscariot_ (166362) | more than 9 years ago | (#12270505)

  • Bullet points, not paragraphs!

If your product has a UI (2, Insightful)

mveloso (325617) | more than 9 years ago | (#12270508)

If your product has a UI, then the design document should start by describing the UI and how all the features work.

If you don't have a UI, then start from the configuration file or command line switches, and do the same thing.

Then you're done. If you can't configure a feature, or can't trigger it from the UI, then it shouldn't exist...unless there are other interaction points.

If you have a network app, document the wire protocol, range of input values, and expected behaviors (of your app and its clients) and outputs.

If it's a distributed system, figure out the different states and document them.

It's actually a pretty simple, though tedious, process. Starting from the UI is a great place, because it shows you instantly how complicated your app is. If it's too complicated, this type of document will show that pretty quickly.

What Makes a Good Design Document? (4, Insightful)

Anonymous Coward | more than 9 years ago | (#12270510)


At least for most of the projects I've worked on.

If all fails.. (0)

Anonymous Coward | more than 9 years ago | (#12270512)

>> if all else fails, where's a good place to find all this stuff out?

fastForward (till the end of the project)

Look (comments)

If (no comments){



Document the choices (2, Insightful)

tcopeland (32225) | more than 9 years ago | (#12270515)

Don't document every function and class. That's useless; let Doxygen or Javadoc do that.

Instead, document why you chose PostgreSQL over [foo]. Why you chose to roll your own templating system. Why you fork off jobs in a separate process rather than doing them in one process. Why you wrote this particular thingy as a C extension.

Documenting that stuff will be helpful to folks down the road when requirements/environments/whatever changes and they wonder why things were done this way in the first place.

There is no perfect design document.. (1)

Kalroth (696782) | more than 9 years ago | (#12270522)

.. and if there is, I've yet to see it. :-)

Short answer:
Some UML (Use Case + Activity + Class) documents and a technical textual description of the task.
You can of course add more, but in 99% of the time, the programmers will either ignore or overlook it.

Long answer:
We (small software business) are working on making our inhouse design documents more standard.

One of the things we ran into was also the "What should we assume to be basic knowledge for a design document" question and after having spent some time, we came to the conclusion that design documents had to be so basic that you can replace a programmer in almost any state of the project.

Based on above we made an estimate on how long it'd take to make the proper documentation, showed it to the manager, got a swift "fsck no!" reply and went back to the old system of poor documentation, but high productivity (and many bugs ;)

Personally I try to aim for the "three developers" goal. If three non-involved developers can understand it and come to the same conclusion as me, then it's all good.

Simple (1)

dfn5 (524972) | more than 9 years ago | (#12270541)

A document that accurately specifies what the customer needs as opposed to what they asked for.

Test Driven Development, User Stories (1)

shapr (723522) | more than 9 years ago | (#12270546)

My preference is to get a list of features from the customer in the form of User Stories [] , and turn those directly into Acceptance Tests [] .
Tests tell you what to do, and when to stop.
I also put a rough estimate on the various user stories, and then let my client prioritize the stories so the work I do first is what they want most.

In many cases, clients don't know what they want until you don't give it to them. The best approach I've found for those cases is to whip up a tiny prototype to show to the clients and ask them what they like and don't like about that prototype.
Clients know what they want, but they rarely understand what's hard and what's easy when it comes to software.
So, I think design documents are best as a bunch of 3x5 cards holding user stories, along with matching acceptance tests.

IEEE Standards!!! (1)

ShyGuy91284 (701108) | more than 9 years ago | (#12270553)

As I have learned from classes, following IEEE standards to the T!!!!! Go 830-9993........... What? You mean there's more to writing a good document then following the standards? Impossible.......

Wiki? (2, Interesting)

adz (630844) | more than 9 years ago | (#12270554)

Has anybody tried using a wiki for the design documents? Might help keep the documents correct and up-to-date.

Find the Guru (2, Informative)

StarWynd (751816) | more than 9 years ago | (#12270559)

The primary problem is that there's too much information to document. I could create a document which included every design decision and every little facet of the project, but the document would wind up so huge, it'd be impossible to work with. The best resource I know of is the project guru. Every project has one -- the one guy who seems to know everything or at least can tell you where to find the details. Find this guy and pick his brain as much as you can. That'll carry you a lot farther than the documentation itself. However, if the guru is no longer around, you're up a creek without a paddle.

!Who! Makes A Good Design Document (1)

Fox_1 (128616) | more than 9 years ago | (#12270561)

A Good Product Manager
This person should follow the development of a product from beginning to end, and document as well as be responsible for the production of the Design Requirements.
The Product Manager should work in the business/marketing side of the company, as ultimately the customer will determine the success of the product, however they should have a strong enough background in the technologies that they aren't some caricature from a Dilbert cartoon. It isn't necessary to define individual segments of code since the basic technologies may change by the time the project moves to design and later phases - but the end results of the implementation of the elements of the product should be documented, the developers can then always know what their product should be capable of. Of course everybody who does work should be documenting their work and ideally to document specs laid out by the Product Manager to ensure consistency with all the product materials.

Re:!Who! Makes A Good Design Document (1)

Fox_1 (128616) | more than 9 years ago | (#12270641)

I left enexplained and likely understood I hope that the PM coordinates regular meetings (with agenda's, minutes and all that) on the products design, development, and testing on a regular basis (weekly)with all involved parties (devs,QA,Mkting,etc) to ensure that the product is matching the expectations laid out in the documentation.

Cohesiveness (1)

behindthewall (231520) | more than 9 years ago | (#12270572)

I have worked for organizations that uses Lotus Notes extensively.

[diety] save me from documentation that consists of links upon links upon links. I certainly find this disconcerting, and I imagine I'm not the only one in that execution based on these documents often seems disjointed with significant factors going lost in the process.

Whatever you put together, try to ensure it's not blown into thousands of pieces. Documentation requires some effort; updating should be more than just glomming on a paragraph at some document boundary or via yet another link to an independent context (independent document). The payoff is when you can actually get an overview of what you (and OTHER teammates) are doing, in a reasonable amount of time and with a reasonable amount of effort.

It also protects your organization from the proverbial "run over by a bus" (as in, the only one who knew this just was...).

Model Driven Development (2, Interesting)

chong (67651) | more than 9 years ago | (#12270573)

I've had excellent success with model-driven development.

The basic process is : create a model that encapsulates the three bigs:

1) Analysis (i.e. requirements, actors, and use cases)
2) Components (object models, system models)
3) Interactions (interfaces and sequencing)

Once your model contains a good description of these three domains, expressing a design document from the model is straightfoward (indeed, many of good modellers will provide excellent document generators). XDE works fine, but my particular favorite is Enterprise Architect []

The beauty of treating the design document as an expression of the model is that by changing the model, you change the document.

In a situation where you're doing large scale code-generation from the model, you're living high on the hog - one repository for your solution information, and any number of expressions of that information into the formats you need (requirements docs, design artifacts, codebase, etc...). By actually including the analysis elements of the solution (the requirements, particularly), you can link those requirements to system components that fulfill the requirements. As the requirements change (and, of course, they will), you can evaluate the impact of those changes quickly by tracing the associations.

Decent article on MDD []

not so much design documents... (1)

LegendOfLink (574790) | more than 9 years ago | (#12270574)

In my experience, I'll be honest and tell you that design documents are a pile of crap. They're usually written from a limited point of view with the assumption that you understand all the nuances of the business. Most of the time, that is not case.

You're a lot better off talking to the key people involved in either the business process or decision making. If you're working for a smaller company, this is relatively easy to do; however, if it's a larger company, I would think it's more difficult (ie less access to the managers). But find out how the process works and what people are looking for in a system.

The key to obtaining the right information is to ask the right questions. Don't approach with, "Hey, I'm designing a new system, what are your needs?", but rather approach with questions regarding problems with the current system. Then, when you get a feel for everything, you can design a system that will fit the right needs.

Don't forget Requirements (0)

Anonymous Coward | more than 9 years ago | (#12270577)

Design is the "how", a tactical plan that requires the "why", or the strategy. What functionality is required? The strategy is often not in place.

Requirements documentation is the "why" and the strategy driving the software development. This should be done before the design and is almost always neglected. This becomes more important with either feature creep or software maintenance. The "why" will always help to keep focus on the important factors in mind.

If requirements change, there is often a value attached to those changes. As a result, the justification for increases in development are often understood and accepted. In the outsourcing development world, it is also the basis for a contract to show that the program meets the needs of the customer.

Keep it up to date (1)

mosabua (534503) | more than 9 years ago | (#12270601)

There is lots to say about design documents but one thing I always find to be lacking is how up to date the documents are. Mostly they are written for some sort of release and then left untouched again until the next one. That's bad. Enforce that any change to the software in terms of features and requirements has to be documented as part of the implementation task. No bug or change requests gets closed without the documentation being done and being up to date... Hard to achieve but once you documentation is concise AND up to date you will be a great step closer...

Most Important part of Design Document (3, Insightful)

Loitl (876962) | more than 9 years ago | (#12270602)

The most importnat part of a design document is to document what is NOT going to be implemented.

Reference the requirements. (1)

JustNiz (692889) | more than 9 years ago | (#12270605)

Yep. Reference the requirements document from the design document, showing how aspects of the design address each particular requirement.

You may also find it useful to split the design document into a hierarchy of many; one or more high-level documents for module-level descriptions, each having one or more low-level design documents for stuff like unusual algorithms or other non-obvious aspects of the design of a particular module.

Good Writing (1)

EEBaum (520514) | more than 9 years ago | (#12270607)

A good design document, like any technical document, should be well written. All too often, something that could take a sentence to write is expanded into multiple paragraphs or even pages, because the writer likes to feel important. Keep it relevant, and keep it simple.

Also, despite what they tell you in academic paper-writing classes, it's *all right* to write in everyday language. A statement such as "The user moves pointing device A over the activity area of the button in question, intending to activate Process Retroincabulator, and presses the button of activation." can easily be replaced by "Click button A."

Less is more. Each unhelpful word the engineer has to read in a hopelessly long design document brings them one step closer to "Screw it, I'll do it my way and get yelled at later." Reread and revise, removing as much unnecessary verbage as necessary.

General principles (1)

turg (19864) | more than 9 years ago | (#12270609)

The basic idea behind writing anything right is to know your audience. You've used these documents before -- write out a list of all the information you, as a user of these documents, need to get out of them to do the work properly. The format, etc., should support the answering of these questions -- don't decide on a format/structure and then shoehorn the information into it.

peer scrutiny (1)

spyrochaete (707033) | more than 9 years ago | (#12270611)

The best thing you can do is compose an outline or draft and show it to as many people as possible. Get feedback, criticism, and suggestions, and update the outline. Then get feedback again. The more eyes, the fewer mistakes.

The Test Plan *IS* The Design Document (1)

rewinn (647614) | more than 9 years ago | (#12270612)

No matter what the official titles may be, the real design document is the test plan.

This is because if the product should accepted if and only if it satisfies the test plan. A good test plan will thoroughly exercise the conditions that the product will encounter, and specify the expected response. Once you know those things, generating a traditional design document is trivial (plus or minus nontrivial graphic design).

Because PHBs expect something called a Design Document, I suggest you build a database of Product Condition/Responses (e.g. "Condition: Push Red Button; Response: Sound Klaxon") which you can sort one way to produce a design document and another way to produce a test plan. This is not intended to be cynical; design documents may need to be organized differently than test plans.

Not sure what type of design document. (1)

Voidwalker (876958) | more than 9 years ago | (#12270620)

I've taken a few software engineering courses, there are two main documents of a design spec. I'm not sure from your post whether you're lumping them into one or not, but they are Requirements Definition and Requirements Specification. Look up ANSI/IEEE Standard 830 for the full blown layout of these things. You can tailor them to suit your needs (not all the guidelines need to be followed)

se8 with a trollkore (-1, Offtopic)

Anonymous Coward | more than 9 years ago | (#12270621)

code sharing writing i5 on the

Try Joel for a good Functional Spec description (5, Informative)

rmerrill11 (308424) | more than 9 years ago | (#12270633)

I think that Joel Spolsky addresses software design docs well. Among other things, at one time he was responsible for writing the software spec for Microsoft Excel.

This series of articles is about functional specifications, not technical specifications. People get these mixed up. I don't know if there's any standard terminology, but here's what I mean when I use these terms.

  1. A functional specification describes how a product will work entirely from the user's perspective. It doesn't care how the thing is implemented. It talks about features. It specifies screens, menus, dialogs, and so on.
  2. A technical specification describes the internal implementation of the program. It talks about data structures, relational database models, choice of programming languages and tools, algorithms, etc.
When you design a product, inside and out, the most important thing is to nail down the user experience. What are the screens, how do they work, what do they do. Later, you worry about how to get from here to there. There's no use arguing about what programming language to use before you've decided what your product is going to do. In this series, I'm only talking about functional specifications."

One of his books: Joel on software []

His blog: What's a Spec? []

Highly recommended!

How does MS or other 'big' ones document software (1)

dilan (73502) | more than 9 years ago | (#12270634)

I have never worked for a large software company. How is a large design effort that goes into something like Windows or Oracle documented and maintained. I am sure these companies would separate people from processes and maintain the independence.

After the design document comes (5, Insightful)

rjh (40933) | more than 9 years ago | (#12270657)

... the "this is how it really works" document. That's what you're really interested in. There's nothing wrong with the design documents you've seen.

No, I'm not kidding.

The design documents which have driven you mad probably weren't incomplete. They were probably quite complete design documents. But a complete design document isn't supposed to cover everything. If you had a design document that was fully specified in every significant detail, you could run the design document through a compiler and generate your code. (This isn't as far-fetched as it sounds; there are tools to automatically generate large amounts of code just from simple UML diagrams. That's an example of design documents being translated directly into running code.)

A design document can best be viewed as the development team's prejudices regarding the best way to solve the problem. There will be holes in the design document, mostly in those areas where the programming team doesn't really have a good grasp on what the best thing to do is.

A good design document is a like a good steak; they're best when served a little bit rare. You want to give the guy who comes after you a game plan, but you don't want to commit yourself to doing things in one particular way when you don't know if that one particular way is going to work. After all, once the design document has had every stakeholder sign off on it, going back to the drawing board and saying "uh, this isn't going to work, let's try something else" means all the stakeholders get back on board again. But if the design document has some room to move--what you think are "holes"--then that gives the programmers freedom to get the job done without having to go through the entire design approval bureaucracy again.

Most serious software engineering shops worship at the altar of requirements and architecture documents. Hackers in the trenches add the "this is how it really works" document to that list. There's nothing quite as valuable as stumbling across some prior hacker's notes when you're trying to grok the system.

Stop looking at the design document for the 'missing' stuff. It might very well have been deliberately omitted. Start asking around for the "this is how it really works" documentation, instead.

explain why (1)

senahj (461846) | more than 9 years ago | (#12270671)

Every design involves choices and tradeoffs.
Each of these requires a decision.

In order to intelligently maintain and extend
the project, the owners need to know why each
decision was made: what were the design goals,
what were the available alternatives,
what were the constraints, and what might be
done under different alternatives or constraints.

That is, explain why the design is the way it is.

"This algorithm has n-squared behavior, but
was easy to implement and test. N-squared
behavior is tolerable for a small number
of fazzbarns, and we are fairly certain that
no more than a few fazzbarns need ever be supported.
If the glup module is ever scaled up to produce
more fazzbarns, this will be a bottleneck, and
the well-known but much more involved RTTD
(Right Thing To Do) approach, with n*log(n) behavior,
would be much better."

He's no fun; he fell right over.

Requirements are the foundation! (2, Insightful)

mikesmind (689651) | more than 9 years ago | (#12270681)

You can write the best design document around, but if it doesn't address the requirements, it won't produce a good result.

I think that most requirements gathering activities don't involve the right people. Most importantly, they should involve the developer. I have seen requirements sessions involving only the business analyst, an IT lead, and the project manager. They leave out the developer! Usually it is done because the developer is busy with other things.

If you leave the developer/programmer out of the requirements work, they never get the opportunity to understand the requirements and ask questions as the requirments are formed. If you do these two things, you will get much better designs.

I like to include the "why" (1)

WarmBoota (675361) | more than 9 years ago | (#12270685)

I like to describe why I did things in a particular way. Much of what ends up in a design document describes what the system does (I can run the app to see that), or how it does it (that's what the code is there for and I guarantee that the code is more recent than the design document).

What always gets me is when I show up and ask "Why didn't you use XXXX?" No one knows. Often there is a really good reason that I find out after weeks of unsuccessfully attempting to implement XXXX.

Like the Yeti (0)

Anonymous Coward | more than 9 years ago | (#12270698)

In 20+ years of programming, admittedly all in groups of 15 or fewer programmers, I have yet to see a good design document. Most design documents are obsolete as soon as a significant amount of code has been written.

in English (2, Insightful)

kin_korn_karn (466864) | more than 9 years ago | (#12270700)

Having someone that can speak and write English do it will go a long way. My current project is working from a design generated by an Indian guy that has no clue what half the words in the language mean. I resent having to rely on half-assed work when I'm not in a position to advise on the design. It's not hard to run the grammar checker.

Don't document your code. (2, Insightful)

ring-eldest (866342) | more than 9 years ago | (#12270705)

How does the classic quote go? If it was hard to write it should be hard to understand.

Video game design documents... (2, Insightful)

creimer (824291) | more than 9 years ago | (#12270708)

Video game design documents are tricky beasts.

If the design document is underweight, it was good enough to trick the bean counters into giving up the first check. But you really can't use it to build test cases out of it since the developer can add or subtract whatever they want.

If the design document is overweight, you can build test cases with a fair degree of accuracy over the life of the project. The problem is that some developers will bristle at being held accountable for every detail promised and don't like their milestone checks being held up until they deliver the goods.

The ideal design document that lays out what to expect without too much overwhelming detail and the developer delivering to full spec on time probably doesn't exist. At least, not in the video game industry.

Software Engineering 2005 == Medicine 1805? (4, Insightful)

gvc (167165) | more than 9 years ago | (#12270713)

Much of software engineering is received wisdom. It involves little engineering and even less science.

I draw the analogy to medicine in the 19th century because at that time physicians were finally trying to investigate the causes of disease and developing insight that, more than a century later, would lead to their interventions improving rather than diminishing life expectency.

Nobody knows what "best practice" should be, yet we're codifying a process. The design document is one aspect of this process. Rarely is the purpose of a design document to convey design. Rather, it is a "deliverable" presented to a PHB or client as evidence of progress. To this end, the larger and prettier it is, the better.

When to write a design document? (1)

teetam (584150) | more than 9 years ago | (#12270714)

In companies with strict processes around design documents, usually there are rules to make sure design documents are written and approved before coding happens.

However, most of the time, the code rarely stays true to the design. Things come up and the code has to keep adapting and changing. By the time the software is released, the design document reflects the original intent and not really the actual design of the system.

As a result, it less useful and may even be misleading to someone new.

If we do the opposite and let developers write design docs after coding, there is often very little interest in work that is already done, so the docs turn out to be very sparse.

IMHO, the best design documents are closely tied to the code itself and constantly gets reviewed as a part of the code reviews as well. That is the only way to make sure relevant information is documented and that the document stays fresh.

good code (2, Interesting)

fermion (181285) | more than 9 years ago | (#12270716)

I have worked on three or so real legecy projects, not to mention going back to my own old code. In each case the official documentation has been hopelessly out of date. What saved me is the quality of the code. Even in the most archaic languages, good developers self document in such a way that other good developers can easily understand and map the process.

Good design documents show intent, but it is the code itself that determine the process. It is like a factory. One has draft and official procedures, but it is the marked up copies on the floor that indicate what is actually going on.

Amazingly, I find this somewhat harder to do in OO languages. The flow is often not as clear due to polymorphism and the like. Makes coding easier, but sometime reading harder. I guess it is just a matter of manners.

Good requirements = good design (2, Insightful)

jmh_az (666904) | more than 9 years ago | (#12270732)

A good design document starts with good requirements. It also requires that your process have some way to capture and fold changes back into the documentation as necessary.

A good place to look is "Software Requirements--Revision" by Alan Davis (1993). I don't agree with everything Davis has to say, but the book is full of good ideas and potential "gotchas" to watch out for. Another good reference is DO-178B, the guidelines used for the development and testing of safety-critical software in commercial aerospace applications. It is available from the RTCA [] for about $50.

If you're doing an OO project, then you might want to look at Booch's book: "Object Oriented Analysis and Design" and the UML 2.0 specification .

But, most importantly, you MUST have some kind of design documentation (requirements, at a minimum) and that documentation needs to be flexible enough to accomodate changes without causing everything else to grind to a halt while the revisions happen. Expecting to get good software with inadequate formal documentation, minimal planning and insufficient requirements is why 70% of all commercial software projects end in failure (documented and published statistic).

Anyone who says you can do good software by shooting from the hip is nuts. And they don't work for me.

What Makes a good design document (0)

Anonymous Coward | more than 9 years ago | (#12270757)

There is no "best method". There are however, some good cliches to follow:

1. Less is more: The less detail you go into the more likely it will be relevant.
2. A picture is worth a thousand words: simple high level diagrams are good.
3. If you have nothing to say, say nothing at all: write documentation because it is needed, not because you feel you should.
4. Don't be a copycat: If the code documents what needs to be said, don't duplicate the code in your documentation.
5. Those who can not remember the past are condemned to repeat it: Team knowledge is your greatest resource. A "living history" will give you a better understanding of a piece of software than a document ever can.

Where I am working we are experimenting with using a Wiki for writing and maintaining documentation. It might be worth your looking into.

Also, using something like javadoc for documenting you classes and class files is probably better than writing a separate document.

OO UML (1)

Yakasha (42321) | more than 9 years ago | (#12270768)

I've found most useful three things:
Class Diagram
Use Case Scenarios
Flow Chart

The class diagram I think is the single most useful doc for any OO project. It tells exactly what the package/application/whatever can do, and often gives some insight into what the designers were thinking.

Use case scenarious tell you how the designers imagined the program would be used. You can also ask users to write down how they envision their interaction with the program.

A flow chart or state diagram or something similar for the app if needed. The larger the app, the more useful this is.

Design docs are like flowcharts (1)

AppyPappy (64817) | more than 9 years ago | (#12270779)

Design docs are like flowcharts. You write them AFTER the system in implemented. That way, you don't have to explain why the system doesn't fit the documents.

Keep it living, be complete (1)

mikeborella (118715) | more than 9 years ago | (#12270783)

I try to keep mine current, revving them after peer reviews, low level designs, test plan reviews and customer discussions. I also try to be as complete as possible, within reason, so that the outcome (i.e., what the product actually does) is predictable. A hard thing to do is maintain traceability between requirements and the resulting software and test plans, and I've not seen good tools to do so (I've seen lots of tools, but they all seem to require too much overhead).

Once I have a solid design doc for a feature that is released and dpeloyed, I turn the doc into an Interface Control Doc or incorporate it into an existing one, which is then kept current with subsequent changes.

None of this is perfect but it seems to work and is fairly low-overhead if everyone buys into the process.

impossible problem (1)

king_ramen (537239) | more than 9 years ago | (#12270795)

Things that get FULLY documented become so obtuse, esoteric and bureaucratic that they can never actually work without huge teams of people. Look at CORBA, X.500, iCAL, and government defense contracts.

Things that are over simplified (HTTP,SOAP,SMTP) take off quickly and people are left to their own devices to fill in missing protocol gaps, causing huge future headaches.

The best way to split the difference is to make LOTS of simple design docs that allow for multiple iterations, where no single document becomes a monster (the CORBA spec is currently over 1000 pages).

Look at IEEE standards. (4, Informative)

rleibman (622895) | more than 9 years ago | (#12270798)

I'm not totally sure what you mean by Design document, I've seen many software shops. Some call the requirements document design, while others define the design document as the document that describes the high level description of the internal architecture of the system (system diagram, major modules, client/server decomposition, class diagram).

Either way, I like to start with some templates I created based on IEEE standards, a few come to mind, Here's the list:

IEEE standards pertaining to sofware engineering [] . In particular take a look at the Software Requirement Specifications and the software design descriptions.

Some of these are very documentation intensive, but I find that at least reading through them when starting a new project helps me direct my thoughts and make sure I don't forget anything that might be relevant to the phase in question (what? I need to think about the maintainability? the stability? the robustness?) pick and choose those things that apply to your project.

Pictures! (1)

PromANJ (852419) | more than 9 years ago | (#12270803)

Every time I want to check out a game I go straight for the screenshots. A picture says a thousand words and all that. Pictures at the start of the doc are a good way of quickly explaining what it's roughly about.

I think another important thing is to explain why you made certain decisions. Just stating things like facts and leaving out your justification and thought process will make you decisions seem like arbitrary opinions.

Naming characters Azearoth and Kyliandra is not game design. Keep things fuzzy, details later. The concept should work on an abstract level.

Doxygen... (1)

zarthrag (650912) | more than 9 years ago | (#12270806)

"...Make that shit up as you go!"

Docs! Docs! We don't need no steenking docs... (1)

pottymouth (61296) | more than 9 years ago | (#12270809)

Documentation is a good place to start and it may give a reasonable overview (sometimes) but I've found the best place to start is with the people that are still on the project that have written what already exists. Use their knowledge and their experience with the specification to first get a feel for how things lie and where they need to go next.

Written docs vary so much in accuracy and detail. It's too easy to read docs and think you know how things work just to find out that's where things started but now they're completely different. Sometimes the docs you have can really mislead you and waste your time. Start with the people, then do a quick once over of the docs, then start reading code. That's the way to get an accurate picure as quickly as possible.

Design Dialog (1)

xbytor (215790) | more than 9 years ago | (#12270811)

I frequently find that design documents do not have enough of the reasoning behind why a decision was made. Issue Based Information Systems (IBIS) is one way of recording this information and I have seen people use this technique successfully. But what may be of more value is to setup a designated mailing-list/newsgroup/blog/journal for the project that can be accessed (online and searchable) in addition to any formal documentation that is generated.

Hate to Say It (2, Insightful)

Stormcrow309 (590240) | more than 9 years ago | (#12270813)

Read Wieger's Software Requirements [] from Microsoft. It is a very good book to work on. Mainly, our process is:

  1. Get User Requirements By Process Reviews, Functionality Studies, and User Panels
  2. Translate Everything into Use Cases
  3. Write User Requirements Document, specifying everything into Must Haves, Nice Haves, and Too Bads
  4. Have technical team review and impose technical requirements and organizational standards
  5. Write Software Requirements Document from User and Technicals Docs

At least that is what we try to do. Half the time, it is 'You bought what?'

Read Joel on Software (2, Informative)

(nil) (140773) | more than 9 years ago | (#12270814)

Painless Functional Specifications [] --not precisely what you were looking for, but pretty close, I think.
Load More Comments
Slashdot Login

Need an Account?

Forgot your password?

Submission Text Formatting Tips

We support a small subset of HTML, namely these tags:

  • b
  • i
  • p
  • br
  • a
  • ol
  • ul
  • li
  • dl
  • dt
  • dd
  • em
  • strong
  • tt
  • blockquote
  • div
  • quote
  • ecode

"ecode" can be used for code snippets, for example:

<ecode>    while(1) { do_something(); } </ecode>