View Full Version : Design documents in the real world?

02-07-2006, 03:38 AM
My professor keeps putting major emphasis on design documents, and I'm just wondering how practical they are in the industry. How do they compare to interaction diagrams, flow charts, etc?

What experience do you all have in your everyday work/programming?


02-07-2006, 04:15 AM
your diagrams become part of the entire set of design documents.
On their own they mean nothing.

In practice, You tend to either be swamped by a deluge of documents and diagrams (so many in fact that they're useless because they're too much) or you get little of anything at all and basically have to figure everything out for yourself.

The ideal would be documents that are detailed enough to tell you what the customer/user wants without going into scrutinising detail (I've seen design docs listing every single method and variable, even private ones, with name and type, that's clearly too detailed).

The functional design should tell you what the application should do, what user interaction it should have, and ideally include things like use cases, screen mockups, and things like that. A statement as to the available resources for the application to run on, what style (webapp, client/server, etc.) should also be there.
The technical design then goes into more detail, describing the public interface for toplevel classes, how screens interact, application architecture in general.
That's where your other diagrams come in, but don't get tempted to overspecify here too.
You shouldn't as an architect worry about whether your programmers are going to use a LinkedList or a Double LinkedList internally for a local cache they may need for example.
Leave them some creativity or they get bored and leave.

But like I said I've yet to see that in 8 years in the industry in a variety of companies from large to small.
The large ones tend to set too much emphasis on the paperwork, yielding thousands of pages of documents for a program that may have a single screen with 2 buttons, the small ones tend to not have any documentation at all.
Worst of all are the small ones thinking they are large ones, they tend to focus on producing documentation like there is no tomorrow but they don't know how to do so so produce documentation that is worse than useless.

02-07-2006, 08:20 AM
A year ago I wrote up some of my observations on the software process and documentation. I posted it to my livejournal (http://filker0.livejournal.com/21947.html#cutid1), so I won't retype it in here.

I've worked at places where the design documents were useless, and others where they were essential. I've also worked on projects where there were no design documents, unless you include "README.1ST" and "TODO.TXT" files. I believe in design documents, but I don't believe in them describing everything and taking away the creativity of the programmer. jwenting and I agree on that. The document should describe the overall structure of the program, but unless a detail is important to other parts of the project or is an essential core algorithm, the detailed decisions should be left to those people implementing the system.