We didn't need documentation back then!

Ever been in that situation? A product has been in development, from the ground up for three to four years. There have been several sales and the product is overall regarded as rather successful. In fact, it grows much bigger than initially expected. An infrastructure forms around it, staffing demands grow, etc. etc. until at some point the company is big enough that an actual HR department is justified. Then, the core developer decides to move on and is off to greener pastures. Ouch.

It gets worse: He or she did in fact never bother to create any elaborate documentation of the architecture or any important design decisions. It's all in his head.

Well.

I overheard a similar description the other day. Interestingly, the speaker concluded his story with the following statement: "We did not need to create documentation for anything back then." Nodding, chuckling ... then the conversation moved on to other subjects.

I could not forget about this though. On the one hand, I do empathize with the spirit: You're having a high tech startup, so you work hard, really hard to get out that product. You have only one or two people hacking away on the code. You're exploring new territory and have to hurry, because the competition could enter your market any moment. You really a) have no time for documenting, b) see no reason, because the application is far from complex at that point, and finally c) only need a minimum of documentation simply because there is not a large team involved and thus pretty few things to be communicated. No time for breaks, because you and your team are busy inventing the future and selling the half-ready program to cash-wielding prospects who would prefer to have the final result tomorrow. It's a pretty exciting environment.

Not creating effective documentation in that early stage of a product is a horrible mistake.

Here are just some reasons for this:

  • As more and more requirements are revealed software tends to gain and not lose complexity.
  • The software (or rather, the code base) will end up being in use far longer than the original developers could possibly anticipate.
  • Teams will grow, requiring a great information overhead. It can be very painful process, trying to discover the existing knowledge about architecture, design or features.
  • People will move on. They may move within the company or sign on somewhere else. Either way, the transition can be quite slow and inefficient. If the former main developer is suddenly busy running the company he won't have much time explaining database table structures.
  • The early knowledge may well be core knowledge, if the early development focused on the most important features of the application.

There is of course no easy answer, because some of those earlier objections may well appear quite valid. For some time anyway. Then, you better have a plan on how to transition smoothly to a good documentation process. Otherwise you might just find yourself in an unlucky scenario five years down the road.

Most value during development

I think there's a great point in there, that even though documentation is primarily intended to be used in the future for looking back, it's biggest value is often at the time it's written. If you're taking over or looking back, no matter how much documentation you have, sooner or later you're going to have to dig into the code.

Drawings

Personally, I think better with pictures - class diagrams, flow models, database schemas, etc - as opposed to raw text. Being able to see how it's *supposed* to work gives me quite a bit more information than how things *could* work.

I'm also a big fan of the JavaDoc-like tools. They're not perfect and can't document everything, but it's better than nothing especially if you don't want to dive into the code.