We were out boating last weekend (as usual) and there was a group of folks on our friend’s sailboat that began discussing software. Someone causally commented that software, of course, can never really be documented. “Right,” said another. “If you try to document it, then the code changes, and so the documentation is always out of sync. It’s impossible!”

All agreed that design documentation maintenance is an unattainable goal. Some were engineers from a big major networking company, one from a mid-sized software company.

But the advantages of having a real “As Built” spec seem so obvious. A spec that is always updated before code changes are made, that is used by QA for testing and used by Tech Support for customer support and questions, a spec that unquestionably contains the use case scenarios and business algorithms implemented by the code. The advantages of having such a spec is so key to producing clean, quality code and so necessary for clear communications between the developers and the customer advocates (Product Marketing, Tech Support) that it seems to me an obvious requirement for effective software.

Yet these software professionals were in agreement that maintaining such a spec is not feasible. Perhaps I shouldn’t have been surprised. When interviewing candidates recently for a VP of Engineering position, I repeatedly found each candidate had a similar story – whether from a small start-up, a major application vendor, or somewhere in-between – each said they had never found a way to successfully document and track requirements to design to code. It wasn’t feasible, each said. Plus others I knew from a mid-sized software application company had same opinion. Product Marketing creates the Marketing Requirements Document in Microsoft Word. Engineering takes that and creates the design and then codes. At the end of the cycle, although the PM team attempts to maintain the MRD in-sync with the code, they say it isn’t ever really possible. Plus because some MRD documents describe enhancements to existing modules, they are “change” documents, and after a few releases there was no complete document defining the complete feature. One solution companies have tried is to assign the task of writing an “As Built” document to the Technical Documentation team after the code is released. Seems like a good idea? It would only be valid if the document were thoroughly tested by QA but that would require double-testing so is never done. Hence it’s only the tech writer’s best guess at specifying what the code is actually doing.

Yet I still thought these companies were anomalies. Even though, my friend and consulting partner, Anita continually encounters the same feedback from the students in her UC Santa Cruz training courses on requirements management, it seemed that these companies must not represent the majority. Surely most companies must have found the solution. Because the solution was not that hard to find.
But to hear again this weekend the wide-spread belief that maintaining design documentation isn’t viable me stop and take notice. I know the “Agile Software” community discusses the advantages of relatively sparse use of documents. But seems to me that the discussion is at the wrong level. By eschewing documentation we are losing a key component of an effective software process.
And what I’m advocating doesn’t need to take more time or effort. In fact, just the opposite. There is a level of documentation that can be easily maintained, aids every organization throughout the software company, and should be as much a part of a normal software development cycle as configuration management tools are. (Hopefully no one reading this blog would tell me they do not believe in checking software into a configuration management tool). Maintaining real, code-synchronous documentation is feasible and just requires the right tools and corresponding processes.

Yes – it’s an easy problem to solve. At Azerity, my company, we proved that having the right process and not only were feasible, the result was reduced headcount needed to design, develop, and maintain code. It was actually amazing at the size and complexity of software we were able to deliver and support with so few people. And a key component was the concept of complete, “as-built”, tested specs describing each application module. These specs became core to our company, our software bible, the key to our IP, and only the code itself was more revered and protected.

Our journey – how we got there. For the first few years as a start-up, we had effective processes for our size company because we had implemented, from day one, our Tracker tool (see Tracker tab) which was much more effective than open source tools like Bugzilla, JIRA or their equivalents. For a team of less than ten with an application still small enough that key individuals could grasp the entirety of the product in their heads, we were able to implement and enhance the application effectively using only SD Tracker, CVS for code management, and MS Word for specs.

But then we got larger quickly as a company and the application grew. We doubled the engineering team. With plans to double the engineering staff once more we had a major expansion of new modules and enhancements being designed by our new Product Marketing team. We were becoming a real software company.

We hired a VP of Engineering and I took on the CTO position. Her first observation upon arriving was that using MS Word for specs wasn’t going to continue to be viable. And it was quickly apparent that she was right. We had a new Product Marketing team that were making spec changes, the developers were having difficulty tracking what changed from revision one, two, three of the Word docs. Some companies try to handle this by checking the Word documents into a code management system but that still doesn’t help the engineers clearly identify the delta between the spec and existing code.

Anita, our new VP, had recently completed a requirements tracking tool comparison at her prior company and Telelogic’s DOORs product (now owned by IBM) was the clear choice. We decided we didn’t need to re-evaluate tools and we purchased DOORs.

The beauty of the DOORs product is that it is similar to using Word so is easy to learn. But most importantly each requirement is automatically tagged with a unique ID that stays with the requirement even if you cut and paste and totally reorganizes the document which isn’t possible with Word or any tool that claims it can export and re-import to/from Word. Each requirement can also be tagged with other attribute columns. For example, we added a Tracker number attribute and other columns. Since DP Tracker was used for change tracking, workflow, developer and QA assignments, and ongoing developer/PM discussions, the Tracker number tied the spec changes to the developer’s work list and the rest of the software process all the way through to QA and deployment. Each time we made a spec revision in DOORs, the latest version was exported to centrally stored HTML files which all developers could access without having to own a DOORs license. Hence although requirements tracking tools are quite pricey, by only having to purchase licenses for the few key individuals that updated the specs, it was still an affordable tool. Tracker also linked to our code management system (CVS) so we had a complete, consistent tracking from specs to completed code to test. I’ve performed a lot of evaluations of similar tools over the years and unfortunately find that most lack some of the key features that made DOORs so effective. Hopefully IBM will continue to support and maintain DOORs. The IBM sales representatives seem to be pushing their Rational tool for software requirements tracking but it is missing key components we found so important.

There were two results of implemented process: (1) Because our tools were linked (DOORs, Tracker, and CVS) the result was a consistent flow from what Marketing was requesting in behalf of the customer, through design, code, test and delivery. In other words, the engineers actually built what the customer wanted and could do so with less time and energy. And (2) DOORs contained true “As Built” specs. QA tested against the DOORs specs as part of their standard testing and so the company was assured that what DOORs contained matched the actual code. Because the DOORs specs were accurate, other teams (Technical Support, Professional Services, Sales) could quickly access (via the HTML exported pages) exactly what the code did or did not do.

The DOORs specs were not design docs in the true sense of the word. No UML or lower-level implementation concepts. DOORs documented the user scenarios (screen shots and descriptive text), business functions, as well as lower-level information (business algorithms, policies enforced, and even database schema). They contained everything needed to communicate organization-wide what the software was supposed to do and did do.

And this approach simplified everything. Engineers were happy because they had clear direction about what to change when. And if a customer reported a “bug”, there was an easy way to tell if it was really a “bug” (developer mistake) or new, previously unidentified need because if it was in DOORs but the code didn’t work that way, it was a bug. Otherwise, not a bug. Code didn’t change without the spec being updated or, if the spec was found to be missing key information, the specs were always updated and tested so always both items, spec and code, were always in sync. The specs were a living, breathing documents. And this streamlined process and total consistency throughout the software life cycle has been proven to improve quality, reduce the delivery time, and enable technical support to provide better customer support with fewer people. Win-win-win.

Contact Jan or Anita if your company does not have a low-cost, high quality software process including a complete set of “as built” specifications for your code. We can help implement the Azerity process and tools at your company to help you sail smoothly through your software development cycles!