Designs should be documented and kept up to date
Some people think that doing a design or documenting the design is not important. I often find that this is the perception of people who have not worked in a team before. If you are the only developer on a project you might not need to communicate concepts and ideas to someone else. But this changes when someone else needs to start working on the same project. Suddenly you need to start explaining to Jane how things fit together and why certain decisions were made. At that point, design documentation becomes very valuable.
Design documentation allows us to clearly communicate high-level concepts, policies, and decisions, leaving out unnecessary details.
It is easier to start with a high-level overview of the system and work your way down into the
details. If we start by looking at the detail (the code), instead of the design, then there is too
much information and it becomes difficult to separate the important high-level concepts & policies from the unimportant low-level details.
When I get involved in a project that I know nothing about, I always ask to see the design documentation before looking at any implementation details (code or databases). More often than not I get one of the following responses:
What design documentation? The code is the documentation.
or:
We have some design documentation, but the code is so different from the design now that we should just look at the code.
So the 2 main problems with design documentation are:
- not having any
- and, not keeping the design documentation up to date as the system changes over time.
Keeping the design documentation up to date is also important. Out of date documentation is
misleading and is not useful when we need to communicate our design. It is better to have no
design documentation than to have out-of-date, or misleading documentation. To help with this, I got into the habit of changing the design documentation first, and then making the change to the code.
Every time I build a system, I create use-case diagrams, domain model diagrams, and state diagrams, as necessary. This really is an important step, even if you are the only one working on the project right now. You never know when someone else needs to help out. Every time someone joins my team, I always start with going over the design documentation.
One other thing about design documentation is it should be light-weight, not taking more than 3-4 days to create. To get this right takes practice. You have to figure out what details are important enough to add to the design, and which details to leave off.