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.
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.
21 comment(s)
Getting user interface questions on the under-budget UI sure sucks the big one.
Anonymous on Saturday, May 10, 2008I think the solution to this issue may be software product lines.
Anonymous on Sunday, May 11, 2008Documentation 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.
Jack Diederich on Sunday, May 11, 2008I think you meant "hermeneutically confusing" (gak!) rather than "hermetically confusing." The first relates to interpretation, the second to hermits.
Owen Byrne on Sunday, May 11, 2008> 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.
Douglas on Sunday, May 11, 2008The 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.
Jordan Bettis on Sunday, May 11, 2008ask bir hayal izle
ask bir hayal izle on Sunday, October 04, 2009nice article. keep post like this...
Fendi replica watches on Tuesday, July 20, 2010Your post is really informative for me. I liked it very much. Keep sharing such important posts..
U-Boat replica watches on Saturday, July 24, 2010PerformingGraham for sale that will create a one-wayswiss watches backlink to your website whichMaurice Lacroix watches is a good point to have. It is Patek Philippe watchesa time-consuming Tag Heuer for saleprocess even though it produces good outcomes U-boat for saleand works. You can also swiss watchespost comments on blogs alongMaurice Lacroix watches together with your link, but make sureGraham watches these blogs are do-follow, which dolce & gabbana handbagsindicates the link that youreplica coach handbags simply post will probably be replica handbagscounted by the search engines jimmy choo replicaas a backlink.There are many thingsversace replica handbags that contribute to online businessjuicy couture replica failure, and the lack of good action thomas wyldeis surely one of the deadliest business-killersdolce gabbana handbags on the net. Take action like by no means chloe handbags replicaprior to, and don’t get struck by analysis paralysisburberry replica. Your achievement lies in your rapid actionchanel replica and how well you apply numerous strategies.
replica watches on Saturday, July 24, 2010nike air jordan 2010 nike air jordan 5 nike air jordan 3 nike air jordan 11 cheap nike air jordan 2 nike air jordan 1 nike air jordan shoes discount nike air jordan shoes nike air jordan 6 wholesale nike air jordan 1 discount nike air jordan 6 nike air jordan 7 nike air jordan 8 top quality nike air jordan shoes 23 nike air jordan 21 nike air jordan 22 nike air jordan 6 rings cheap nike air jordan 22 nike air lebron james shoes nike air lebron james shoes nike air jordan 2010 nike air joredan lebron james nike air jordan 2009 discount nike air jordan 2009 nike lebron james wholesale nike air jordan 2010 cheap nike air jordan 2009 discount nike air jordan 19 cheap nike air jordan 3 discount nike air jordan 18 brand nike air jordan 12 wholesale nike air jordan 2 nike air jordan 13 nike air jordan 14 nike air jordan 6 rings discount jordan shoes7 discount jordan shoes1 jordan shoes2010 jordan shoes 6 rings cheap jordan shoes2 discountjordan shoes3 discount jordan shoes4 jordan shoes uk23 jordan shoes classic bw22 cheap jordan shoes 21 ltd discount jordan shoes20 discountjordan shoes19 jordan shoes 18 uk nike air jordan shoes 17 cheap nike air jordan shoes 16 discount air jordan shoes 15 discount air jordan shoes 14 nike air jordan shoes 3 uk nike air jordan shoes 13 cheap nike air jordan shoes 11 discount air jordan shoes 6 discount jordan shoes 10 nike air jordan shoes 8 nike air jordan shoes 7 cheap louis vuitton bags cheap kobe bryant shoes cheap lebron james shoes .
cheapjordan on Saturday, July 24, 2010I will keep visiting this blog very often. Blu ray to iPad /
ipad converter on Sunday, July 25, 2010The variety links of london items bearing depends on the occasion. You are plain, but you are elegant. links of London sweetie braceletIf presence a groove, especially nightfall outfit, you are allowed to be very gentle in truth. What you should do is to links of london charms choose some delicate sweetie bracelets with your subtle sensation of fashion on Christmas Day, Easter, Halloween and Valentines Day. Discovering links of London friendship bracelet on the net is an excellent choice for your needs and can also assure you may benefit from the best insurance coverage at the best price tag. The links of London braceletis one kind of those brands that basically level the start a time honored design and style and design untreated. links of london necklace and links of london earringswill be the consultant of level and higher personal taste; so many people contain the hopes for donning links of London sweetie bracelets. Nevertheless, in the large price, so most of us cannot pay the big money. links of London friendship bracelets charm bracelets links of london sale charm bracelet silver friendship bracelets links of london charm bracelet
links of london on Monday, July 26, 2010ed hardy, cheap ed hardy, ed hardy clothing, ed hardy outlet, ed hardy jeans, ed hardy bags, ed hardy swimwear, ed hardy shirts, ed hardy tee, ed hardy caps, ed hardy purse, ed hardy board shorts, ed hardy shoes, ed hardy for men, ed hardy for women, ed hardy jeans for women.
cheap ed hardy on Tuesday, July 27, 2010ed hardy, cheap ed hardy, ed hardy clothing, ed hardy outlet, ed hardy jeans, ed hardy bags, ed hardy swimwear, ed hardy shirts, ed hardy tee, ed hardy caps, ed hardy purse, ed hardy board shorts, ed hardy shoes, ed hardy for men, ed hardy for women, ed hardy jeans for women.
cheap ed hardy on Tuesday, July 27, 2010Buy at lower prices replica hangbags and shoes and save up to 80-90%. Buy Handbag Louis vuitton. We are a Louis vuitton outlet store and offer cheap replica
Gillette holds strong as the “best for men” for personal care, owning 70 percent ... The lv brand is also gathering strong momentum in China,
YouTube streaming video - Louis vuitton Journeys: the greatest game - For the world cup 2010 lv outlet launch a special ad campaign with
louisvuitton4 on Thursday, July 29, 2010I love Louis Vuitton products, but I hate, hate, hate their Louis Vuitton purses! After years of searching, I think I've
honestly found the best ...
Welcome to our site,All Best Louis Vuitton bags and fashion Louis ... Choose Louis Vuitton
wallet, for a taste, an experience, a lifestyle.
A store selling replica Louis Vuitton and Chanel handbags, wallets, ... (b) using the Louis Vuitton in connection with the sale
of any
Louis Vuitton Best Humanoid Award. Since 2002, Louis Vuitton has sponsored the “Louis Vuitton online shop” for
RoboCup, an international research and
West offer best cheap designer HOT fake fashion unique best Louis Vuitton Bags outlet cheap 2157 wholesale,discount
replica HOT fake fashion unique
louis vuitton on Thursday, July 29, 2010Wholesale NFL Jerseys
Cheap NFL Jerseys
NFL Jerseys
NFL Football Jerseys
Women NFL Jerseys
Kid NFL Jerseys
Super Bowl Jerseys
Super Bowl NFL Jerseys
Throwback Jerseys
Throwback NFL Jerseys
Cheap Throwback Jerseys
Wholesale Throwback Jerseys
Cheap Super Bowl Jerseys
Wholesale Super Bowl Jerseys
youth nfl jerseys wholesale
youth nfl jerseys cheap
nfl youth jerseys
Baltimore Ravens Jerseys
Chicago Bears Jerseys
Cincinnati Bengals Jerseys
Denver Broncos Jerseys
Dallas Cowboys Jerseys
Green Bay Packers Jerseys
Indianapolis Colts Jerseys
Minnesota Vikings Jerseys
New England Patriots Jerseys
New Orleans Saints Jerseys
New York Jets Jerseys
Arizona Cardinals Jerseys
Buffalo Bills Jerseys
Atlanta Falcons Jerseys
Carolina Panthers Jerseys
Cleveland Browns Jerseys
Houston Texans Jerseys
Detroit Lions Jerseys
Jacksonville Jaguars Jerseys
Kansas City Chiefs Jerseys
Miami Dolphins Jerseys
New York Giants Jerseys
Philadelphia Eagles Jerseys
San Francisco 49ers Jerseys
Oakland Raiders Jerseys
Seattle Seahawks Jerseys
Pittsburgh Steelers Jerseys
St Louis Rams Jerseys
San Diego Chargers Jerseys
Tampa Bay Buccaneers Jerseys
Tennessee Titans Jerseys
Washington Redskins Jerseys
Ray Lewis Jerseys
Ed Reed Jerseys
Joe Flacco Jerseys
Terrell Suggs Jerseys
Dick Butkus Jerseys
Greg Olsen Jerseys
Matt Forte Jerseys
Devin Hester Jerseys
Walter Payton Jerseys
Brian Urlacher Jerseys
Lance Briggs Jerseys
Jay Cutler Jerseys
Carson Palmer Jerseys
Rey Maualuga Jerseys
Chad Johnson Jerseys
Demarcus Ware Jerseys
Jason Witten Jerseys
Terrell Owens Jerseys
Felix Jones Jerseys
Marion Barber Navy Jerseys
Marion Barber Jerseys
Emmitt Smith Jerseys
Miles Austin Jerseys
Roger Staubach Jerseys
Troy Aikman Jerseys
Tony Romo Jerseys
Eddie Royal Jerseys
Brandon Marshall Jerseys
Aaron Rodgers Jerseys
A.J. Hawk Jerseys
Donald Driver Jerseys
Greg Jennings Jerseys
Peyton Manning Jerseys
Dallas Clark Jerseys
Robert Mathis Jerseys
Marvin Harrison Jerseys
Drew Brees Jerseys
Marques Colston Jerseys
Pierre Thomas Jerseys
Reggie Bush Jerseys
Jeremy Shockey Jerseys
Tarvaris Jackson Jerseys
Adrian Peterson Jerseys
Jared Allen Jerseys
Mark Sanchez Jerseys
Thomas Jones Jerseys
Leon Washington Jerseys
Brett Favre Jerseys
buynflshop on Thursday, July 29, 2010retro jordan vibram five fingers vibram five fingers Bikila ugg australia air force one vibram five fingers sale vibram five fingers running ugg uk air jordans vibram five fingers classic Vibram Five Fingers Classic winter boots jordan 1 vibram five fingers flow vibrams five finger shoes fur boots air force ones vibram five fingers kso Vibram Five Fingers Flow ugg sale air retro jordan buy vibram five fingers vibram finger five ugg boots sale jordan 11 vibram five fingers size Vibram Five Fingers KSO ugg boots uk jordans shoes vibram five fingers shoes vibrams five fingers classic tall jordan 12 vibram five fingers women vibram five fingers ugg boots cheap jordan 5 new vibram five fingers buy vibram five sheepskin shoes new jordans cheap vibram five fingers vibram five fingers running shoe uggs sale jordan shoe vibram five fingers surge running in vibram five fingers uggs uk jordan 13 vibram five fingers kso black vibram five finger toe shoes boots footwear jordan 4 vibram five fingers discount vibram five fingers women's celtic sheepskin jordan sneakers vibram five fingers reviews vibram five fingers barefoot shoes love from australia retro jordans vibram five fingers shoe buy vibram five finger shoes sheepskin boot xi jordan the vibram five fingers vibram five fingers KSO Trek slippers boots jordan 23 vibram five fingers ebay vibram five fingered classic tall chestnut jordan kids vibram five finger running to buy vibram five ugg australia sale cheap jordans vibram five fingers hiking Vibram FiveFingers MOC Black sheep skin boots cheap jordan vibram five fingers Bikila vibram five fingers Performa ugg boats michael jordan shoes vibram five fingers Performa vibram five fingers hiking celtic sheepskin company air force one shoes vibram five fingers Performa Jane vibram five finger running ugg australia retro jordan shoes Vibram Five Fingers Sprint vibram five fingers sizing ugg uk dunk shoes air jordans 4 vibram five fingers Performa Jane winter boots jordan iv air jordans 5 vibram five fingers mens fur boots jordan retro 11 air jordans 7 vibram five fingers dealers ugg sale jordan air force rare air jordans vibram five fingers womens ugg boots sale air force 1 shoes air jordans 8 Vibram Five Fingers Sprint ugg boots uk authentic jordan air jordans buy vibram five fingers for sale classic tall jordan brand air jordans for kids vibram five fingers store ugg boots cheap jordan 20 air jordans for cheap vibram five fingers fitting sheepskin slippers new jordan shoes discount jordan shoes air jordans 1 sheepskin shoes jordan retro 5 retro authentic jordans authentic jordan shoes uggs sale cheap jordan shoes air jordans 3 jordan shoes for sale uggs uk air jordans shoes jordan 21 shoes jordan xx boots footwear jordan dub zero jordan 23 is back rare jordans celtic sheepskin jordan sneaker air jordans for girls jordans shoe love from australia jordan xiii cheap air jordans shoes jordan xxi sheepskin boot jordan xii air jordans for women wholesale jordan shoes slippers boots authentic jordans air jordans sneakers kids air jordans classic tall chestnut jordan retro 4 air jordans shoe jordan xix slipper sheepskin retro air jordans exclusive air jordans air jordans for sale ugg australia sale cheap air jordans jordans 23 buy jordan shoes emu slippers all jordan shoes jordan 2 retro air jordans 11 sheep skin boots jordan 5 shoes rare jordan air jordans 13 ugg boats jordan retro 3 authentic air jordans air jordans wholesale celtic sheepskin company jordan vii new air jordans custom air jordans michael jordan sneakers buy jordans purple coach purse coaches handbags coach outlet red coach purse coach op art handbags op art sabrina coach bag coach handbags black coach handbags summer coach handbags summer coach purses coach tote coach baby bags spring coach handbags spring coach purses coach wallet coach bag sale find a coach outlet coach leather book tote coach discount new coach bags coach leah op art coated canvas top handle tote coach op art handbag coach handbags outlet coach tote handbags coach sabrina op art coach book tote coach sandals new coach handbags coach vintage coach op art tote coach luggage buy coach purses discount coach handbags coach madison op art tote coach jewelry coach wallet sale coach baby bag coach z spring coach bags buy coach handbags coach handbags corporate vibram five fingers discount uggs sheepskin footwear ugg boats vibram buy cheap ugg boots ugg australia online celtic sheepskin company five fingers knitted ugg boots australia classic tall sheepskin footwear vibram five ugg boats australia women's classic cardy ugg australia online vibram five fingers classic cheap ugg boats genuine uggboots australia classic tall five fingers vibram buy ugg site ugg 5815 women's classic cardy vibram shoes buy discount ugg boots ugg 5825 genuine uggboots vibram shoe Ladies UGG Boots ugg 5803 ugg 5815 vibram five fingers flow UGG boots sale ugg 5819 ugg 5825 vibram fivefinger ugg boats ugg 5833 ugg 5803 vibram kso UGG Classic Tall 5815 Boots ugg 5879 ugg 5819 fivefingers kso ugg 5879 ugg 5854 ugg 5833 Vibram Five Fingers Sprint ugg 5803 ugg 5359 ugg 5879 vibram five fingers bilika ugg 5819 ugg 5325 ugg 5854 Vibram FiveFingers MOC ugg 5833 ugg 5225 ugg 5359 vibram five fingers performa ugg 5854 celtic sheepskin company ugg 5325 vibram five fingers performa jane ugg 5825 sheepskin footwear ugg 5225 celtic sheepskin company ugg 5815 ugg australia online ugg boats sheepskin footwear ugg 5359 australia classic tall celtic sheepskin company ugg australia online ugg 5325 women's classic cardy sheepskin footwear australia classic tall ugg 5225 genuine uggboots ugg australia online women's classic cardy 2010 Hot Selling Boots ugg 5815 australia classic tall genuine uggboots celtic sheepskin company ugg 5825 women's classic cardy ugg 5815 sheepskin footwear ugg 5803 genuine uggboots ugg 5825 ugg australia online ugg 5819 ugg 5815 ugg 5803 australia classic tall ugg 5833 ugg 5825 ugg 5819 women's classic cardy ugg 5879 ugg 5803 ugg 5833 genuine uggboots ugg 5854 ugg 5819 ugg 5879 ugg 5815 ugg 5359 ugg 5833 ugg 5854 ugg 5825 ugg 5325 ugg 5879 ugg 5359 ugg 5803 ugg 5225 ugg 5854 ugg 5325 ugg 5819 celtic sheepskin company ugg 5359 ugg 5225 ugg 5833 sheepskin footwear ugg 5325 ugg boats ugg 5879 ugg australia online ugg 5225 celtic sheepskin company ugg 5854 australia classic tall celtic sheepskin company sheepskin footwear ugg 5359 women's classic cardy sheepskin footwear ugg australia online ugg 5325 genuine uggboots ugg australia online australia classic tall ugg 5225 ugg 5815 australia classic tall women's classic cardy sheep skin boots ugg 5825 women's classic cardy genuine uggboots ugg boats ugg 5803 genuine uggboots ugg 5815 celtic sheepskin company ugg 5819 ugg 5815 ugg 5825 sheepskin footwear ugg 5833 ugg 5825 ugg 5803 ugg australia online ugg 5879 ugg 5803 ugg 5819 australia classic tall ugg 5854 ugg 5819 ugg 5833 women's classic cardy ugg 5359 ugg 5833 ugg 5879 genuine uggboots ugg 5325 ugg 5879 ugg 5854 ugg 5815 ugg 5225 ugg 5854 ugg 5359 ugg 5825 ugg 5854 ugg 5359 ugg 5325 ugg 5803 ugg 5359 ugg 5325 ugg 5225 ugg 5819 ugg 5325 ugg 5225 ugg 5833 ugg 5225 ugg 5879
ugg on Friday, July 30, 2010Want to get Ed hardy at home? No hesitation, get them at with big discount. We are promise you that all the ed hardy clothing are good in qualities. Meanwhile, buying ed hardy clothing online, that’s never a bad idea. By the way, whenever and wherever you need us, we will be there for you. Ed Hardy T-Shirts are waiting for you now, welcome you!
ed hardy on Friday, July 30, 2010