Thread: Design documents in the real world?

  1. #1
    Registered User
    Join Date
    Dec 2002
    Posts
    56

    Design documents in the real world?

    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?

    Thanks

  2. #2
    chococoder
    Join Date
    Nov 2004
    Posts
    515
    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.

  3. #3
    Sr. Software Engineer filker0's Avatar
    Join Date
    Sep 2005
    Location
    West Virginia
    Posts
    235

    Documentation and process

    A year ago I wrote up some of my observations on the software process and documentation. I posted it to my livejournal, 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.
    Insert obnoxious but pithy remark here

Popular pages Recent additions subscribe to a feed

Similar Threads

  1. Too much to ask ?
    By deflamol in forum C Programming
    Replies: 2
    Last Post: 05-06-2004, 04:30 PM
  2. Hello World in Windows
    By FearOfTheDark in forum Windows Programming
    Replies: 2
    Last Post: 01-08-2003, 03:02 PM
  3. Who should rule the world?
    By CoderBob in forum A Brief History of Cprogramming.com
    Replies: 7
    Last Post: 02-07-2002, 07:01 AM
  4. Replies: 7
    Last Post: 12-12-2001, 10:28 AM
  5. No More Technology After World War Three
    By Unregistered in forum A Brief History of Cprogramming.com
    Replies: 16
    Last Post: 09-20-2001, 07:02 PM