It's Independence Day in the US, but today, let's instead celebrate our dependence on good quality documentation. It matters. Even when we measure the size of that documentation in meters, instead of freedom units. Original -- Remy

Just about all of the systems I’ve written about here share quite a few things in common: they are poorly designed, poorly coded, and even more poorly documented. Today, I’m happy to share with you a system that doesn’t quite fit in with all the rest. It’s actually very sound software and, most of all, it’s well documented. Very, very well documented.

George Nacht is a software engineer in certain a Post-Communist European country. In the mid-1990’s, his government decided that it was time to replace their foreign, Soviet-era fighter jets with modern, less expensive aircrafts of domestic design. And since they were modernizing their fleet, they decided to modernize their pilot training as well. This meant that new, interactive flight-simulator software needed to be developed.

Instead of going with an incredibly expensive, all-encompassing defense contractor, the Air Force decided to try something new. They awarded the contract to the small game development company that George worked for. Though it was their first government contract, they were confident that they’d be able to deliver the project on time and within budget. After all, the software required was actually less advanced than the flight simulator they had developed earlier: no “high score” tables, flashy animations, or anything like that. Just the basics.

George’s contact at the Air Force was a gruff, old general with a vast knowledge of aerial warfare and forty years experience in the service. Naturally, he was very skeptical of the new guys’ ability to develop a “military grade” product.  After all, they hadn’t spent a single day in uniform. But George’s team quickly won him with a demonstration: one month after being awarded the contract, they had fully replicated the prototype plane’s specifications in their software.

In less than a year, they completed the adaptation of their flight simulator to work with the fancy training hardware. And by fancy I mean a full-sized cockpit with six display screens, sixteen force-feedback motors, and an absurd amount of buttons and controls. Everyone loved it. Pilots said it flew like the real thing and the general was thrilled to be able to experience flight (albeit, simulated) once again.

“Gentlemen,” the general started during one of their wrap-up meetings, “you have done very well. I am very impressed. There is, however, one problem. You did not provide nearly enough documentation.”

George’s boss nervously chuckled, unsure whether the general was being sarcastic or not. After all, they did deliver nearly 500 printed pages of diagrams specifications. An awkward silence ensued.

“You see gentlemen,” the general continued, “for such expensive program, we require at least eight meters of documentation.” He stretched his arms as far as he could to illustrate. Clearly, he was not joking.

George’s team had no idea how to meet this requirement, so they just started printing. Everything. Source code, screenshots, log files, hexadecimal dumps, emails, resumes. And they found out that –  even with big fonts, think paper, and double spacing – it’s pretty damn hard to fill eight meters (that’s nearly two stories, twenty-six feet, or 320-inches) with paper.

After a few weeks of printing and binding, they were finally ready to deliver the documentation. Arriving at the archive facility with a small truck, they unloaded the boxes of paper and met the general. With an approving nod and smile, he led them through a labyrinth of shelves and cabinets. They stopped at one with exactly eight meters of free space and labeled with the name of the flight simulator project. It was right between the shelves containing “Section F” of the T-72 battle tank specifications and a series of old tomes labeled List of Suitable Locations for Auxiliary Cemeteries.

They loaded box after box onto the free shelf. Without opening a single book, the general thanked them for creating such extensive documentation. Although those boxes will never be opened again, George and his team went home happy to have contributed a flight simulator for their country’s defense program.  And, of course, eight meters of documentation on it.

[Advertisement] ProGet’s got you covered with security and access controls on your NuGet feeds. Learn more.