Slashdot Mirror

← Back to Stories (view on slashdot.org)

What Makes a Good Design Document?

Posted by Cliff on from the techincal-writing dept.

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."

11 of 461 comments (clear)

  1. Design Document by goretexguy · · Score: 5, Funny


    Dee..zin...dok...u...ment...?

  2. The problem. by ShaniaTwain · · Score: 2, Funny

    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.

    --
    Starsucks
  3. Mythical Creatures by telecsan · · Score: 4, Funny

    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.

  4. Steps to writing a good design document by GillBates0 · · Score: 5, Funny
    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).

    --
    An Indian-American Hindu committed to non-violent thought/speech/action alarmed by the global explosion of radical Islam
  5. Re:Duh by Anonymous Coward · · Score: 0, Funny

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

    Just sayin'.

  6. Re:A Good Design Document by Anonymous Coward · · Score: 5, Funny

    Ironically, I had to look up "vernacular."

  7. It doesn't matter .. by Stavr0 · · Score: 2, Funny
    as long as you don't forget to include your TPS report cover sheet.

    (ducks)

  8. Re:Duh by winwar · · Score: 2, Funny

    So, the class DID prepare you for real life then, didn't it :)

  9. Re:Most Important part of Design Document by fraudrogic · · Score: 5, Funny

    Ah yes...the infinitely outlined requirements document is my favorite:

    1.1.1.1.1.1.1.1.1 The system shall not make tacos on demand.
    1.1.1.1.1.1.1.1.1.1 The system shall not make tacos on demand with sour cream.
    1.1.1.1.1.1.1.1.1.2 The system shall not make tacos on demand with guacomole.
    1.1.1.1.1.1.1.1.1.3 The system shall not make tacos on demand with cheddar cheese.
    1.1.1.1.1.1.1.1.1.3.1 The system shall not make tacos on demand with sharp cheddar cheese.
    1.1.1.1.1.1.1.1.1.3.2 The system shall not make tacos on demand with mild cheddar cheese.
    ...

    1.1.1.1.1.1.1.2 The system shall not make CHICKEN tacos on demand.

    ...

    this could get messy.

    --
    I only mod up parents of "mod parent up" posts...
  10. One Simple Rule for a Good Design Document by dbretton · · Score: 2, Funny


    It must compile and run correctly.

  11. Re:Yeah, that's pretty much the distinction I lear by stonecypher · · Score: 2, Funny

    The ideal length for a document is going to vary, project to project, but by building documents in a modular fashion it should be rarely necessary to have a document longer than about 20 sides of A4. Most should be around 10 sides. Anything longer likely covers unrelated topics and can be split up. (Remember, it is easier to open 20 books to one page each, than to open one book to 20 different pages.)

    Yes. Tetris and MS Office have the same target complexity, to within fifty percent. Also, generalizations are helpful.

    --
    StoneCypher is Full of BS