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 www.whatis.com.)

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.