Documentation Dang’it

Documentation

It’s a boring word. It is a word that connotes paperwork, time, and dreary hours spent on a computer. Well, I can’t change this mental image, but I can say what the results could be. Smooth operations, sales and tropical beaches. Documentation is a vital if not critical part of any application, system or process. It will pay off in heaps if done right. Let me illustrate my point.

Case 1: A new application is launched. This new shopping cart is fantastic. Has bells, whistles and even some chimes. The person who set the entire cart in motion decides one day to leave. Uh oh. Now we have a simple situation where the main person has left and you, the business owner, have some new products to get up online. This is a problem. Product inclusion documentation would have been ideal.

Case 2: A new Ajax-enhanced e-commerce site is promised to the CEO by upper management. They said it would be out on a a certain date so the engineers begin to feverishly work on the project. The scope of the project was explained orally. The engineers spend two weeks building when they finally reach the QA phase of the project. They are all plenty smart enough to begin QA for browser compatibility, accessibility and all the basics, but nothing else. Management tells them to go live assuming they remember all the business relationships and logic we have to support. The next day, management has 100 new emails marked urgent. Proper QA was not thorough because there was not a formal document(s) to go along with it. Many people had stakes in this project. A solid MRD (Marketing Requirement Document) or PRD (Product Requirement Document) would have been ideal.

Case 3: Web site XYZ has an e-commerce site that sells all over the world - both tangible products and downloads. A new expensive employee is hired to work on some tax bug. They dig into the code and begin changing things. Engineering gives multiple iterations of how tax is collected. The engineer works on more issues. Errors spring up. Marketing and the sales department are know involved and give different views on how tax is collected. More changes are made. It appears nobody has a solid handle on how taxes are collected. Documentation from management would have been ideal.

Documentation grows, changes and matures as the business changes. Unfortunately, in most companies documentation is the last thing anyone thinks of. It is also the first thing dropped from a project due to hours and budgetary concerns. If done well however, documentation can empower programmers, engineers and optimize the project flow.

http://trac.edgewall.org/ - A killer internal documentation application. Product life cycle, ticketing and technical roadmaps.