(The title of this post comes from one of the Twelve Tasks of Asterix)
Imagine I am working on a research paper. In order to work on this paper, I need to use 7 different document sources:
- 1 laptop
- 1 iPad
- 3 paper documents
- 1 whiteboard
- post-its
Now, imagine that each of these items is physically located in a different room. That would be silly, right? Not only would I lose time constantly going from one room to another, but there would be a high risk of errors, distraction, delays, low morale… Eventually I would just eliminate some sources of information altogether, using whatever the strict minimum is that I need to produce anything I think I can get away with, no matter its quality.
In order to do his/her work, a developer very often has to use quite a large number of sources of information:
- Source code
- Unit tests
- Integration tests
- Functional tests
- Wiki describing the service interfaces
- Design diagrams
- Architecture diagrams
- Business rules
- UI Mockups
- Framework manual
- Deployment console to deploy on the development server
No wonder developers love to have 2 or 3 screens, so they can at least keep all those windows open and navigate from one to the other without losing context!
Still, don’t you think it’s overwhelming? Especially when you know that many items can be merged together.
Take the service interfaces that the components expose, and the source code of those components, for example. Why duplicate the information, especially at two different locations?
What are the chances that one will be changed and not the other? What are the consequences?
What about the requirements? Is it really so hard to find a tool that merges both the UI and the rules?
You can think of tools such as Concordion to document your specifications and make them executable, effectively merging the business rules and many tests.
Even better… I stumbled upon PHPUnit 3.x and discovered the @assert annotation. You can write the tests just above the method body:
/**
* @assert (1, 2) == 3
* @assert (0, 0) == 0
*/
public function add($a, $b)
{
return $a + $b;
}
Wow. What a great idea. You don’t even have to switch to another file!
Of course you can use tools to create the illusion of integration of the documentation sources.
But it’s not the same as actual integration.
For example, if the tool is Eclipse and someone in the team does not use Eclipse, then you have the risk of discrepancies created by the different sources of information.
What about you? Did you find ways to reduce the number of documents required to develop? If so, please share in the comments!
