Development and documentation: A catch 22

This is just an opinion of an aspiring software developer who considers himself as a student more than anything. Please take my opinion in this post with a grain of salt. 

In my opinion, development and documentation form a catch 22 situation. However, let's step back and look at it from a bird's eye view. Software development, and indeed any kind of development activity, does not exist for its own benefit. it exists to serve a business purpose. Indeed, this is following Patrick's writing when he says that software developers should not call themselves programmers in http://www.kalzumeus.com/2011/10/28/dont-call-yourself-a-programmer/. Patrick says the most important business purposes are reducing cost and increasing revenue. Because of economies of scale and other (some of which might not be perfectly rational) reasons, companies grow large. Software development is complicated and big and disjointed teams are formed. Business loves to think about future growth. And business likes predictability and stability. Business needs assurance that solutions outlast their creators. Business wants software developers (just like any other employee) to be expendable. Now, let's switch back to our microscope. 

Development and documentation need to stay in sync. How do we do this? Do we create documentation first (for example, in waterfall method) or do we create prototypes and iterate (agile)? Common sense suggests it is a "safe" answer to say "It depends". My answer is that it does not matter that much. I will explain myself further in a bit. Do we create a proposals and envision different solutions or do we try to implement the first idea that hits our head? Remember, business likes predictability and stability. Success and failure are facts of life but common sense dictates that it is nice to be able to do better than just dumb luck. In other words, we want to be able to reproduce success. This is where documentation comes into play. Good documentation lets us look back into the past and continue with or reproduce success while avoiding the pitfalls and failures without having to relive them, even when different people are involved in the project than the people who were initially there. It follows that bad documentation is worse than useless. Because it is highly unlikely that bad documentation would label itself as bad (and their creators would not because nobody calls his own kids ugly), we will have always difficulty in knowing what documentation is bad without wasting time studying it. 

What do I mean by bad documentation? There are a lot of ways you can create a bad documentation but I am focusing here on out of sync documentation. Documentation that was good but has gone bad. For example, here is a workflow. Business identifies an opportunity. We create proposed solutions to fix the issue. We follow up on the solution that looks most promising. We develop the solution. It is discovered during development that the scope was (big surprise) too narrow and it has to be widened to attain our objectives. The developers, being kind and naive but also under pressure from business to deliver, work more than initially required and create a product that works. However, there is a problem. Nobody ever updates the documentation to reflect the scope change. 

Perhaps it is a good thing to be able to keep documentation in sync to the development no matter what methodology you use. Hey, but what do I know?