Turn Back the Clock and Write Documents After Development?

There’s a scenario I’ve seen play out many times over the years. It happened again just this week. There are many variations, I’m sure. It goes something like this.

A company follows a waterfall approach for software projects. Development teams create requirements documents, functional specifications, technical and design docs — you know the drill. Then there’s the occasional exception. Management decides to fast-track a project. This usually means they give the team permission to skip all the documentation and just write the code.

The approach is justified by claiming that the project is experimental; or a learning experience. After some back and forth, management decides to turn the effort into a product.

This is where things take an odd turn.

I have no problem with skipping steps in the development process to get something done better, faster or cheaper. The odd part is that now management realizes that in order to ship the software, the team must conform to the waterfall process rules. That means all the documentation that was skipped must be written.

So, the team is directed to write requirements, functional specs, tech specs, etc. for a software system that is already built! Does that make any sense?

One argument I’ve heard is that the documentation will be needed in the future as another development team seeks to enhance the system. That strikes me as a shallow argument. The primary purpose of documentation is to serve the needs of the team actively working on a software system. Any future team is likely to examine the source code, data model, and supporting technical documents.

The further documentation is from the end result, the less reliable it becomes.

Should you go back and create a documentation set for software that is already written? If you intend to sell the source code or deliver it to a paying client, the associated documentation may be contractually required. In general, it’s a waste of time and money to turn back the clock and do what you should have done in the first place.

Focus on the future! Am I missing something?

Updated: August 3, 2011 — 10:44 pm


  1. Hi,

    I read the post and realized I did this – I requested technical documentation for a project from the project team, after the project was delivered.

    I personally think it is a good idea in cases of projects that expect maintenance for example, or change requests 2 or 3 times a year.

    If I were a customer, I wouldn’t accept an extra week wait just because the team has to re-study the project, for any feature implementation…

    As you point out in many of your posts, fast (and early, true) delivery is the key and if teams rotate, I believe specific project documentation (tech mostly) is necessary.

    1. There will be exceptions to every rule. Sometimes you are forced to go back and deliver something you omitted. No prob. Just don’t make it a habit!

Comments are closed.