Agile architecture reduces the need for documentation
What is a good measurement of the quality of your architecture? The length of your documentation. The shorter, the better.
There are three purposes of documentation that can be important to a project for its long time survival. First: How does a new developer get started working on the project. Second: How do you install the projects executable on a brand new server. Third: What do you have to know to monitor and operate the system. Projects suffer when these documents are insufficient. However, the documentation is not really the solution. The solution is to get rid of the need for documentation in the first place. Some people misunderstand agile to ignore documentation. My advice is: Don’t ignore it. Write it, and then throw it away. I only say this half in jest. On my current project, the mess that is the totality of our documentation is one of our biggest problems. The problem is that some of the documentation is really needed, and now it’s impossible to separate the good from the bad. If we had been less eager to write documentation and more eager to throw documentation away, we would be in a much better shape now. What is the point of writing documentation if you’re just going to throw it away? Let me illustrate by an example. Recently, after my project got a new test server, I installed the system from scratch on the server. While I did, I kept a log of all everything I did. Then I scrapped the server and did it again to verify my installation log. The log was maybe 10 pages long when I added the necessary comments to make it into an installation instruction. I went over the log and found all the places where I did something that could be removed by improving the code or the installation scripts. Then I threw away the installation log, installed it again and wrote a new installation log. And again. And again. After a day’s work, I had a complete, verified instruction of what was needed to create a test environment. But this time, it was only two pages long. We have gone throw similar processes on how to set up a developer workspace and run the unit tests, and how to run and test the system locally on a developer or tester workstation. The process of reducing the need for documentation improves the system’s architecture. It makes the system cheaper and easier to modify and to operate and monitor. Many of the typical agile practices have a similar result: Good functional tests reduce the need to document the requirements separately. Continuous integration reduces the need to track the state of the quality of the system. If we aim to reduce our documentation, we must automate more, use conventions more, remove problematic technology and generally improve our system. No post can be complete without a suggested practice, and here is this post’s: At regular intervals, you should try to install the development workspace on a fresh computer or install the system on a fresh server. Keep a log of everything you do in this process. Look over the installation log for unnecessary motion and eliminate that motion. Sometimes, eliminating motion can be very hard. One of the elements that really added a lot of motion to all our processes was the IBM WebSphere application server. We had to stop using it to get to a more agile architecture.
Comments:
[Sverre] - Nov 5, 2007
“Agriculture reduces the need for documentation”. That’s what I read. Need to find my glasses.
[Christian] - Nov 5, 2007
Ah, I love the smell of WebSphere criticism in the morning.