You Can't PDF Your Way to Good Software

Thursday, May 08, 2008

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.

Tags: NCSTA, Agile, verbosity

8 comment(s)

Getting user interface questions on the under-budget UI sure sucks the big one.

I think the solution to this issue may be software product lines.

Documentation is nice; documentation at a government level is suicide. Back in my youth my first resume's purpose statement included "working for a CMM 4 or greater" organization. That lasted until I actually talked to industry people. Everyone that followed CMM and ISO standards considered it a great burden that they only complied with (and only kinda complied with) in order to be elligible for government contracts.

I also learned that I really didn't want to work for the kind of company that took government contracts. Large corporations are almost as bad; if you are going to sell to or make something for a bank estimate spending many times the billable hours on talking about the thing as doing the thing.

I think you meant "hermeneutically confusing" (gak!) rather than "hermetically confusing." The first relates to interpretation, the second to hermits.

> All your reader wanted to do was throw up a side window to display the person's name.

And if that's all he did, he'd probably have done it wrongly. Imagine if instead of a name, the window displayed a stock price, and the window was left open for 15 minutes. Then the user decides to invest a $x based on this price using this stale 15-minute old data, and promptly looses $y because the price has changed in the mean time.

Or say one of your windows is an options pallet, but changing one option makes an option in another window inactive. You don't want to have to close then reopen that second window for the option to update. That's where the "data bindable formats for state data" come in.

Perhaps you've demonstrated that verbose specifications are not good tools to learn how to program, and the best you can do is say: if you can't understand the specifications, you're probably not a good enough programmer to follow them. That's the point you go looking for a mentor to make sure you do what you're supposed to.

The reason why government documents are written like that has to do with how the government contracting process (fails) to work.

Basically, if they write a document that assumes that the contractor is both competent and making a good faith effort to produce decent software, and say "well, you know how to write software, please do a good job," then the contractor will hire a couple of language lawyers to figure out what the bare minimum he's required by law to do, and that's what the agency would get. Even for a 50 PDF document like that there are quite a few contractors who try to see if they can't find a few loopholes here and there that'll allow them to cut corners.

I've worked with government people (urban planners) who have to write up bids. They say their professional organization (the APA) provides boiler plate language for them that they can use to specify common requirements. So for instance if they write in the spec "it should have x" then the contractor is likely to give them something that barely satisfies the legal definition of x, so they go to the APA and get 10 pages of boiler plate that precisely defines what 'x' is, and sticks that in the document. So now the contractor has no wiggle room, he has to give them 'x.'

I agree that in an environment where you can assume the parties are acting in good faith, these documents are obnoxiously verbose. But government contractors very rarely operate in the interest of the tax payers or the agency employees who are going to have to use their systems, so the agencies need to make sure all their 'i's are dotted and 't's are crossed to make sure they actually get something that's useful.

Thanks a lot for enjoying this beauty article with me. I am apreciating it very much! Looking forward to another great article. Good luck to the author! all the best!

xlpharmacy

Use the form below to leave a comment.






Coding the Wheel has appeared on the New York Time's Freakonomics blog, Jeff Atwood's Coding Horror, and the front page of Reddit, Slashdot, Digg.

On Twitter

Thanks for reading!

If you enjoyed this post, consider subscribing to Coding the Wheel by RSS or email. You can also follow us on Twitter and Facebook. And even if you didn't enjoy this post, better subscribe anyway. Keep an eye on us.

Question? Ask us.

About

Poker

Coding the Wheel =
Code, poker, technology, games, design, geekery.


Hire

You've read our technical articles, you've tolerated our rants and raves. Now you can hire us anytime, day or night, for any project large or small.

Learn more

We Like

Speculation, by Edmund Jorgensen.