Just how useful is design documentation?

When one begins to learn software engineering, they are usually encouraged to do some form of design before jumping right into the code. I remember some of my first computer science (CS) classes. We had to submit a design document in addition to the source code for any particular project. I remember hating it, but attributing that displeasure more to the fact that the projects were so small and insignificant that they did not really need a design document. After studying software engineering and talking to many different practicing software engineers I realize that design is over rated. I don’t want to say that there is no need for design document, but that maybe too much emphasis is placed on them.

Design documents are really useful to remember information in abstract terms and to communicate with other team members, including management.  When used correctly, they can be a great help for a project.  If the design docs are maintained then bringing in new developers into the project will be easy.  However, most documentation is not maintained, and thus can be very different from what is actually implemented.  This design/code mismatch can lead to lots of problems.  Not only that, the fact that there is a mismatch means there was wasted effort.  If your code looks little like the design, what was the point in spending all that time creating the design docs?

It would be easy to blame poorly trained, “lazy” developers for these problems.  If they would just follow the design docs wouldn’t this just go away?  Well, like everything else, this problem is not so simple.  Due to its complexities, software design is strikingly difficult to communicate.  It tends to be either too high level, and thus leaves a lot of liberties for the implementers, or it tends to be too detailed, thus becoming to cumbersome and difficult to take in.  Also, just to throw it out there, if someone puts together a design that is so detailed that the implementers need to think very little, why not just write it as code in the first place?

I think that it is fair to say that, for any significant project with several developers, the design will be different from what was implemented.  The experience of creating the software will make developers more familiar with the challenges of the domain they are working with and will enable them see better solutions.  And this is where prototyping comes in.

The goal of prototyping is to create a less functional, more cludgy version of the thing you actually want to make.  The prototype is there to not only explore how the application will function in the end, but to also explore how it should be put together.  It is version zero that exists to find potential pitfalls and try out some design ideas.  The goal is not to create something that will become production ready, but to figure out how you will go about creating it. After the prototype is implemented, developers will be more aware of what elements need what information and how communication between different pieces should occur.

An advantage of creating a prototype is that the design ownership moves into the hands of the people actually doing the development.  This gives them more ownership of the product and thus more wllingness to make it better.  It always makes people feel better to think they came up wth an idea instead of some “high and mightly” architect from above.

Yet another advantage of creating a prototype is that it can be shown to the customer.  Prototyping is a great technique for making sure you are actually making what the customer wants and ironing out any communication problems you have with them.  How many developers have experienced customers giving them detailed specifications and telling them that the final product is “not really what we have wanted”.  The goal of prototyping is to catch any incorrect assumptions and make sure everyone is on the same page early in the development life cycle.

I don’t want you to think that I am advocating a complete removal of the design process.  There does need to be a period when one sits down and just thinks about an application.  All I’m advocating is that the design time be kept small and that no one should become too attached to it.  Use prototyping to try out different ideas, there is no need to first describe a class using UML and them implement, why not just implement it and see how it works within the system.  Remember you are not married to the prototype, it’s going to be thrown out.  The goal is to learn from it so that version 1 can be the good one and not something that was kludged together.

Reblog this post [with Zemanta]

One Response to “Just how useful is design documentation?”

Leave a Reply