The Place That Drives You Mad

Too Many Documents

Too Many Documents Required To Work

(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 loose 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:

  1. Source code
  2. Unit tests
  3. Integration tests
  4. Functional tests
  5. Wiki describing the service interfaces
  6. Design diagrams
  7. Architecture diagrams
  8. Business rules
  9. UI Mockups
  10. Framework manual
  11. 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?

How likely do you think one is to be changed and not the other? What are the consequences?

What about the requirements? Can you really not 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. No need to even switch to another file!

Of course, you can use tools to create the illusion of unicity for the documentation sources.

But it’s not the same as actual unicity.

For example, if the tool is Eclipse and someone in the team does not use Eclipse, then you have the risk of discrepancies induced by the different sources of information.

What about you? Did you find ways to reduce the number of documents required to develop? Please share!


About this entry