The documentation black hole

In 2008 I started my second job at a big defense firm. Before that, I worked a couple of years at Mekensleep, a video game studio; it was fun, but I didn’t earn enough to cover my expenses. After the dot com crash there were few jobs for inexperienced software developers.

The defense firm was notoriously cheap; they avoided hiring people with more than a few years of experience. The company was divided in two halves: on one side the full-time employees, who often had only ever worked at the firm; on the other side the contractors who usually left after a couple of years, unless they got a full-time offer before.

It was a dull and stiff environment. I was hired to do UI work in C++. The software I worked on used a proprietary and dated UI toolkit. There was little electronic documentation for it; if we wanted to know how something worked, we consulted one of the 3 thick reference volumes.

The company was top-down and bureaucratic: the bosses made the decisions and the subordinates were expected to execute without any deviation. During the onboarding process I filled a multitude of forms; one of the forms was a request to get another form…

The bosses didn’t trust the developers, especially the contractors. Before committing code changes, we were required to submit a 10+ page Word document detailing all the changes. In practice we’d figure out what to do while writing the code. Once the changes were done and tested, we’d write the document, submit it, wait for approval, and submit the code.

There was no code review, only the design document had to be approved.

I accepted the tedium of writing documentation because, in theory, traceability was useful. That illusion dissipated when I was tasked with reworking a dialog box.

This dialog box interacted with various parts of the system. When I looked at the code it didn’t make sense to me. It was a big bowl of spaghetti code with callbacks arranged in a complicated cascade; a callback triggered a bunch of other callbacks, and there were multiple variables keeping track of what was already done. Despite spending days untangling this mess, I felt there was something I didn’t understand, and since the dialog box was central I feared that I missed something important.

I asked my team’s lead developer to review the code with me and he didn’t understand why the code was like that either.

I looked at the changeset in the version control system. There was no commit message, there was only a reference to the ticket identifier. I decided to ask for the design document associated with the ticket, hoping there would be more details in it.

My manager didn’t know how to get the document; he only had access to the list of proposals submitted by his team. Once he reviewed a design document, it disappeared from the list and he couldn’t access it again.

He asked his peers, and none of them knew how to access the old documents. As far as they were concerned, the change specifications existed only to comply with the ISO 9001 requirements.

Still, my manager thought it was a good idea to try getting it, so he escalated the request to the department’s head.

A few days later the answer came: the design documents weren’t intended to be consulted by the development team; they were reserved for the auditors to ensure the company was complying with ISO 9001. The security team determined that it was too risky to let the developers consult the documentation.

This is the perfect example of following the word of the law instead of the spirit of the law; ISO 9001 was just a box checking exercise for this firm. Traceability wasn’t something that could make our work better; it was only a way to comply with regulations.