TechWhirl Sponsors

About TechWhirl

TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.

For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.

I think there is something to be said about the engineering side of content. Ever since the late '80s our content has become increasingly dynamic. There's good and bad in that. Do two people ever look at the same content? Sometimes they can't! I really P-O'd John Warnock one day by saying static content like PDF was obsolete. He was right... There is value in static content. But there's also value in dynamic content.

In the abstract, what does "dynamic content" mean? It means content has programmable behavior, same as software and robots. Programming that behavior is engineering... Content engineering by definition. What are the necessary components?

* Meaningful content. The author is still the gate keeper, whether a pundit, a Lit major, a robot, or a mob. Editors also...

* Design. Not just the semantic design of your narrative flow (although that must figure into it) and not just the visual design, but the design of the behavioral repertoire (if I can sound posh for a moment). BTW, since it's CONTENT we're engineering, then the behavior must have a semantic component... Every behavioral gesture has meaning.

* Data format. To program the behavior of content, you need it in a format that yields to instruction. Enter XML. It's not a simple matter of plugging in XML... The standard you use must support the design, behavioral and otherwise.

Have I missed anything? Probably, but this is just a stinking list reply.

EXAMPLE:
I'm implementing an online API guide. I want to single-source so I can use the same content for PDF output and for online delivery. I want to author in a straight authoring tool (FrameMaker, it turns out), and I want others to be able to author in a similar tool as well. The online guide includes "sand box" sections where the reader (user?) can fill in forms to create the API call, click a button, and it executes. This is not uncommon -- iodocs is an open source framework for this kind of API doc (https://github.com/mashery/iodocs). But I have to roll my own for various reasons. Anyway, I can author the guide in DITA, and use XSLT to turn lists of parameters into forms that take user input, then assemble and execute the API call. Or I can print it as PDF if I want. I should have this ready for our next product delivery, BTW. Much of this is authoring. Much of it is engineering.

This opens up possibilities beyond API docs... I can use standard tools to create documentation that executes API calls in the product. I can:
* Get the product's current state
* Change the product's current state
* Replicate GUI in the doc -- LIVE
* Show historical lists, maybe to explain the cause of a given state

The list goes on. Take online training for example. People go through the training, and the DOCUMENTATION can evaluate whether they perform correctly. But authoring is done in a product like FrameMaker or oXygen, and you can print a PDF if you like. Once the system is set up, the engineering is done and anybody can add to the content.

Should everybody be doing this? No way. But SOMEBODY has to do it! People have been talking about adding these capabilities to docs for decades now. We're finally at a point where the discussion is getting real. Look at Don Day's stuff, for example. He's reading DITA (could be print-worthy) and presenting it in different, dynamic ways, on the fly. Mark also has done work -- on a thing he calls SPFE. Mark happens to have a (dare I call it?) philosophy that underpins the engineering capabilities he envisions, and happened to write a book about it. So sue him.

As a parting shot, I'd like to point out that a product GUI is nothing more nor less than dynamic content. It's just pretty terse. OTOH, documentation is poised to become an integral part of the GUI -- just more verbose. These are interesting times, and those who want to can step up and take advantage.

cud

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
New! Doc-to-Help 2013 features the industry's first HTML5 editor for authoring.