Progressive Place

Tuesday, June 29, 2004

Web Services IS Documentation

Web Services IS Documentation
(c) 2002 David Calloway. Written 12/17/02.

We're hearing a lot about Web Services (WS) these days. Suffice it to say for now, that it’s a simple idea with a complex implementation, it's easy to misinterpret, and it will ultimately be world-changing.

Ahah! I get it! WS is really all about documentation!
Isn't they? And is it/they singular or plural? Oh, these techies and their fractured syntax.

Technical Writers should give serious attention to WS, and not just for the new wave of grammar-mangling it's launched. "Yes, David," friends would remind me, "You said that about DTP, and BPR, and IMM, and XML, and even about KM and e-Learning." (Sorry, my Acronym Glossary is in the shop for a major upgrade. Meanwhile, try

Well, yes. So I did. And I was right. All those waves did represent major rides for Tech Writers to increase our value to our clients and expand our professional horizons. Some waves we caught and rode, some we tumbled under, and many just passed us by. Why our contribution continues to go under-recognized, in both up and down markets, is a subject for another time.

What are/is Web Services?
What do you think Web Services is about? Is it a new technology, like TCP-IP, HTML or .NET (pronounced "Dot-Net")? No, but it does use all those things, so you'll have to sound like you know something about them.
Essentially, Web Services is documentation. (There goes that darn grammar conflict alarm again.) It's a standard, so what will make it work is everybody agreeing on the rules, and then following the rules they agree on.
Because Web Services is an open standard, every step is a step forward, integrating what came before. A bunch of trading partners gets together, define a standard for exchanging information, and then codifies, writes, & develops processes to fit that standard. From then on, information is exchanged, and things work. As promised. Because the standards were agreed upon by all participants.
At least, that's the idea.

The Web Services Directory
Basically, a Web Services Directory listing says:
· what the Service does
· what it needs to work
- what you can get from it
· what it expects in return.

The Web Services rulebook is called a directory. One offers one's web services to the marketplace by publishing one's offerings to a directory service. To exchange business information through Web Services, partners negotiate the terms and standards that will define their information relationship, and subscribe to the appropriate Web Services.
Directories, publishing, subscribing: This should all be sounding very much like the world that writers have lived in all along.

What's different about Web Services?
You may recall that EDI, EAI, Distributed Computing, and myriad other initiatives have, with high cost and mixed success, attempted to coax disparate computer systems into talking to each other. Web Services is different, because it's anchored not in technology, but in the common dictionary definitions of XML.
Effective XML standards require that data look and act like its industry-standard dictionary entry says it should. You could say it's "speaking the same language", but then one might confuse it with a programming language like C++ or COBOL, which it's nothing like. Here's a better analogy: trading partners agree to use exactly the same dictionary definitions for basic business units like Account Record and Widget. If you can't agree on precisely what each unit is and does, then you can't use XML without an expensive, error-prone translator. And that puts you back where you started, in the expensive, error-prone world of custom-programming.

Raises documentation to new level
To summarize, Web Services is really just a bunch of descriptions. External descriptions are what it is, what it does, what it takes in and puts out, and its expected/desired behaviors and outcomes. Internal descriptions are the data elements, interfaces, interactions, link points, caveats, qualifiers, acceptable ranges, and more (I may elaborate on this later). The pieces described are components, and each component must be described in absolutely granular detail, and with unquestionable accuracy.

The narrative and tables describing Web Services objects to humans is equal in importance to the quality of the systems interface, because they say why and how to use those objects. Long-term competitive success in web services will depend on ever-growing circles of information sharing. The participants who negotiate and implement those business relationships must understand exactly what it is they're agreeing to, and being able to count on accurate, understandable documentation is a big part of that. Because this is all so new to most people, that should include case studies and scenarios, illustrating their intended use. These "stories" are commonly conveyed as Use Cases, using the structure of Universal Modeling Language (UML).

Significance for Technical Communicators
* Code has always existed to support and enable function. The code has never been the function. Developers tend to forget this simple fact.
* The code & functional objects are the means to an end. They are not the end in themselves. Just as Web Services clarify and reveal function more precisely than anything we've ever seen, haphazard maintenance can kill it.
* Web Services and XML exist to communicate among systems, and so depend on communication among humans, through collaboration: standards bodies, specifications, and protocols.

Increasing revenues and profit margins
As the circles of data relationships widen and overlap, the neglected issue of object re-use will become a matter of survival. Not just for revenue opportunities for replication and re-sale, but because the commercial value of objects will rise dramatically in proportion to the level of testing and validation they receive in a variety of conditions.
More thoughts, not integrated into article:
…Commercial re-use of standardized, plug-n-play components will steadily increase licensing and incremental revenues, and thus profit margins. Their documentation can make them sink or swim. Matching quality Web Services with quality documentation, produced by professional technical communicators with equal savvy in technology, marketing, and business collaboration, can make these products fly.

Meet Nick Besser, PI

I'd like to introduce you to my friend and alter ego, Nick Besser, PI. He's choosing to remain out of sight because working as a PI all these years has made him a bit paranoid. I was hoping that meeting you might lighten him up a bit. God must have a sense of humor, and all that.

Anyway, we're hoping to coax Nick in out of the cold to resume his PI practice. In his PI, or "Private Investigator" role, Nick hunts down performance problems and bottlenecks and brings them to justice. As a seasoned professional he works with clients at all levels, creating a custom routine for each engagement. Oh, this guy has some stories! He could speak to industry groups and trade shows to promote HPT, or Human Performance Technology, his favorite methodology for achieving PI.

Actually, what Nick means by PI is as changeable as the weather. One day he'll say it stands for "Private Investigator", and the next day insist it means "Performance Improver". And when a low pressure front's coming through, he'll claim he's off to HQ to "Purge Idiots."

But, beneath Nick's reserve and stoicism, he's really a very deep and heartfelt guy. Although he never knew his real family, they did name him for for "nichts besser", a Germanic expression that means "none better." He considers it his life mission to fuel the drive to constantly grow and improve that he sees in the heart of every human being.

Nick is currently struggling to resolve his identity confusion. For one thing, he can't say whether his Germanic heritage is Amish or Yiddish. In long nights of research on the all-Yiddish search engine,, he disrupt sleepers with shouts of, "Chey, Barkeep! Gimme anudder Belt o' that Red Eye Borscht!"

Ahem. To resume our detailed analysis: Nick has assembled a rather complex identity from watching every episode of Mannix and other 1970s Private Investigator shows. But somehow, Nick has twisted his title to mean "Performance Improver". And occasionally he regards it as a license to Purge Idiocy throughout the organization.

Our own research into Nick's credentials has confirmed that he is impeccably qualified to satirize the current Security mania. And, as Nick likes to remind us, "Not even the bad guys are really all bad."

Our plan is to start out with some short skits, which we will later merge into a one-man show. Nick will then begin to recruit additional characters--covertly, of course. They will then melt away to a top-secret training camp in the mountains, to prepare a series of hard-hitting, action-packed radio dramas. We've already registered the domain name The name "" seems to have disappeared under a cloud of suspicion.

Before you decide to accept any other assignments, I must urge you to come up with some recommendations for upcoming episode themes. Your discretion in this matter is imperatif.

Suspensefully yours,

David C. aka Nick Besser, PI