Here's a rule you software developers out there can take to the bank:

Rambling, ultra-formal specification documents with headings, sub-headings, and dense tracts of text are one of the worst ways to communicate system features, requirements, architecture, design, implementation, or anything else.

Now, don't take offense just because you happen to have authored more than a few such documents in your lifetime. Don't take offense because your organization produces enough throwaway documentation each year to deforest the state of Vermont. We've all done it, and we'll continue to do it, because the next best thing to producing good software is producing a festering sinkhole of documentation just to establish that hey, we're doing important work here. But let's not fool ourselves into thinking that these documents really convey anything meaningful to our readers.

The likelihood of a specification document's actually being read varies inversely with its length.

The North Carolina Statewide Technical Architecture is a reference architecture with which state-funded IT projects are expected to comply. Your state or region probably has something similar, as does every major branch of government and the military. The NCSTA lays out, with impressive verbosity - around 50 separate Adobe PDFs -  the best practices for software development in the sunny state of North Carolina.

It's littered with the language of the software development guru:

User process components coordinate the display of user interface elements. They are abstracted from the data rendering and acquisition functionality provided in the user interface components. Design them with globalization in mind, to allow for localization to be implemented in the user interface. For example, endeavor to use culture-neutral data formats and use Unicode string formats internally to make it easier to consume the user process components from a localized user interface.

And the Table of Contents (from the NCSTA Security Principles & Practices PDF) is downright intimidating:

Now, as a civic-minded taxpayer, and a software developer who reads and decrypts this kind of documentation for a living, I don't even know where to start.

• Why does North Carolina need its own proprietary version of a reference architecture? Aren't the IT needs of North Carolina very similar to those of Virginia, Kentucky, or Oregon? How many millions of dollars did it take to produce the NCSTA? And how many other states have produced something similar? Do we need to reinvent this particular wheel 50 times, one for each state in the union?
• PDF? That's my only format?
• Even assuming North Carolina needs its own proprietary architecture: why is the documentation so formalistic and difficult to read?

On this last point. Take the following paragraph from the NCSTA Microsoft .NET Enterprise Development Guidelines:

Using multiple panes for one activity. If multiple windows or panes are used in a particular user activity, it is important to keep them synchronized. In a Web application, a user interface usually displays a set of elements in a same page (which may include frames) for a given user activity. However, in rich client applications, several non-modal windows affecting just one particular process may be necessary. For example, a product category selector window floating in the application that to specify a particular category, the products in which will be displayed in another window. User process components help implement this kind of user interface by centralizing the state for all windows in a single location. Synchronization can be further simplified across multiple user interface elements by using data bindable formats for state data.

It's trying, admirably enough, to teach you how to synchronize the view of your data across multiple windows. The problem is that, if you can understand this documentation, you probably don't need it. So it's either irrelevant or hermetically confusing, depending on whether or not you know what things like non-modal windows are. (And just for the record: the word is modeless, not non-modal.)

So, how much of the information is really necessary? Assuming you're a fairly competent developer, qualified to read this documentation and implement it in practice? In other words, how much of this information is necessary and/or valuable to its sole intended audience? Well, let's take out our handy magic marker and make some corrections.

Using multiple panes for one activity. If multiple windows or panes are used in a particular user activity, it is important to keep them synchronized. In a Web application, a user interface usually displays a set of elements in a same page (which may include frames) for a given user activity. However, in rich client applications, several non-modal windows affecting just one particular process may be necessary. For example, a product category selector window floating in the application that to specify a particular category, the products in which will be displayed in another window. User process components help implement this kind of user interface by centralizing the state for all windows in a single location. Synchronization can be further simplified across multiple user interface elements by using data bindable formats for state data.

There you go. Simple.

Every last word can be discarded. These words add zero value or knowledge to the world that isn't either a) already known or b) explicitly stated fourteen other times in the labrynthine NCSTA documentation. In fact, the presence of these words provides a negative value. All your reader wanted to do was throw up a side window to display the person's name. Now you've got him off on a tangent, trying to figure out what the hell "synchronization can be further simplified across multiple user interface elements by using data bindable formats for state data" means.

Now the funny thing about all this, is that the NCSTA documentation is a virtuoso piece of technical specification writing if you compare it to the typical specification documents that governments tend to produce, usually under the auspices of "due diligence". So my complaints aren't so much geared toward the author(s) of the NCSTA as they are the entire genre of long-winded technical architecture documents in all their forms, and the institutional malaise that produces them.

In other words, you can't PDF your way to good software development. It's been tried and tried, without success. Consider, in your organization, using more fluent and expressive mechanisms to convey system structure or communicate best practices, and your users will thank you for it.

Posted by James Devlin   7 comment(s)