In one of my most memorable software projects, our team maintained a strong focus on documentation, and it definitely paid off.
The five of us knew ahead of time that there would be only one version of the application, and the development time frame was relatively short (8 months of part-time development), so we followed a waterfall methodology for the project.
I know the waterfall model gets a lot of flak for leading to project failure, but we felt that it was appropriate for our project. The project actually turned out to be a great success, and I’m pretty sure that the methodology had nothing to do with it.
We had many deliberations up front about what features we wanted to include. I remember the meeting well: we brainstormed our ideas over a few pitchers of beer (you know, to get the creative juices flowing) and made a whole bunch of far-fetched predictions about how each feature would integrate into the system as a whole. I remember taking a minimalist stance, knowing there would be no version 2. I argued against implementing additional features “if we had time”. Any additional time would have to be allocated to testing and/or marketing (which ended up just being a nice glossy UI and a nice glossy demo).
Anyway, we used our requirements to develop a specification written in the form of use cases and non-technical requirements. It was about 40 pages, which seems huge for such a small project. The real documentation win came in the form of our 100+-page design document. We got it bound and everything. It was a real work of art, consisting of class diagrams, sequence diagrams, and state charts galore.
But that wasn’t what was so amazing about it. It’s what we did with it that counted.
I remember doing majority of the coding with the document at my side, using it to resolve differences between what I thought during the requirements and design phases and what I was thinking during the implementation phase. All five of us did this. We wanted to make sure that we built the system we planned to build.
The most amazing part of all was our vow to finish the project with all the documentation, coding, and testing plans in sync. So we went back and updated the requirements and design documents with anything we changed as a result of realizing we didn’t initially know what we were talking about. Then we got them bound. Again. We basically rewrote our own history.
The thing that mattered most was that we were all committed to documenting our communication, and then using that documentation for further discussion. We talked throughout every phase of the project. The whole experience taught me that communication is the key to project success. Cohesive documentation is just one way to ensure that the conversation is preserved, and that future team members can join in at any point.
In our small project, it wasn’t our choice of methodology that made a difference; rather, it was our attitude towards the methodology we chose.