Thoughts on “Context-Sensitivity” and Dynamic Output Reconfiguration

I wrote the 2010 trends article for STC Intercom magazine. One of my predictions there was the emergence of “dynamically reconfigurable output,” which I took from an item in the News Digest section of an issue of ComputerWorld from around 2005. That item’s take was that XML, and xMetal in particular, could let us do cool things, such as creating online information that was sensitive to its “context.”

If you’re in tech comm, you may have been doing context sensitive online help systems – that know where you are in the application and display only relevant information – so what’s the big deal? But that wasn’t the idea of the item in ComputerWorld.

The idea there was online information that changed depending on its context, the example being an aircraft service manual whose content changed automatically based on whether the temperature was above or below freezing. (So this manual served two “audiences”.) Or consider smart phone and mobile device apps whose display mode shifts from portrait to landscape automatically, depending on whether the device is horizontal or vertical. (So this manual also serves two “audiences”.)

From tech comm’s perspective, this idea of “context sensitivity” has two interesting angles.

First is simply the idea that “context” means different things to different people and we in tech comm can no longer take that meaning for granted. (The article Context Matters by Beth Schultz, in the September 21/28 2009 issue of ComputerWorld, discussed “context” as the tagging of equipment in a hospital to define its location and make it easier to find. Anyone hired to do “context sensitive help” for that hospital who assumed the standard meaning of “context sensitive” would run the risk of creating the wrong project.)

Second, and odder, is the idea of dynamic reconfiguration as a means of serving different audiences, like below-/above-freezing or horizontal/vertical in the examples above. Such situations are easy to handle using today’s help authoring tools – create one project and, using conditionality and other single sourcing features, generate one version of the output for each audience. We then leave it to some other mechanism to direct users to the right version of the help depending on the circumstances – temperature, physical orientation, etc.

The problem with the multi-output approach is that it’s cumber- some. We have to create one output per audience, which can become challenging as the number of outputs grows. Better to create one output that can modify itself.

We’re slowly heading there. Mark Logic ran a webinar in October 2009 entitled “Dynamic Delivery Is Where It’s At: Custom Documentation From Multiple Formats” that offered some possibilities. And I’ve been told about various proprietary, code-level experiments in online help authoring. I’m just not aware of any developments at the help authoring tool level yet.

If you’re aware of any work on dynamic output reconfiguration using help authoring tools or as proprietary, code-level experiments that can be discussed, I’d love to hear about them on general principles, or possibly as an Intercom column or, if you can get to me between before March 19, possibly as a proposal for the Beyond the Bleeding Edge session at the annual STC conference.

“Beyond the Bleeding Edge” is Back, and Looking for Proposals!

(for STC's annual Tech Comm Summit (aka annual conference) in Dallas, May 2 to 5.)

Sometime between now and May of 2010, might you…

…develop one online document conditionalized to be viewed on a desktop PC and an iPhone?

…create a document containing dynamically customizable content?

…create a hybrid document?

…perform a hard-dollar cost-justification of your documentation group’s work?

…or do something else that’s bleeding edge, and applicable to technical communication?

Many technical communicators are hard-put to keep up with the daily grind, let alone have time to look into emerging technologies. “Beyond the Bleeding Edge”, which debuted at the 1999 annual conference, addresses this by presenting summaries of technologies and methodologies that are too new or unusual to make it into traditional Summit sessions. After a three year hiatus, “Beyond the Bleeding Edge” is back and looking for presenters for the Tech Comm Summit in Dallas.

Is there a technology or methodology that you’d like to discuss? It can be:

· New… Are you creating online help that can change its contents depending on the outside air temperature?

· Existing, but fairly new to technical communicators, like physical context-sensitivity for mobile devices.

To be accepted, a “Bleeding Edge” topic must be fairly new as of early 2010. A “Bleeding Edge” presentation should be:

· Short – You’ll have about 20 minutes to cover your topic and take questions.
· Informal – Attendees prefer handouts but this is at your discretion.
· Level-appropriate – You can cover a topic at whatever technical level you consider necessary as long as you warn attendees what to expect.

If you enjoy new topics and like to discuss them, we want to hear from you. Send your proposals to Neil Perlin, Hyper/Word Services, nperlin@nperlin.cnc.net or 978-657-5464 by March 19, 2010. There are only three slots this year, on Wednesday, May 5, from 8 to 9:15 AM. Slots fill up quickly, so don’t delay!

Question About DITA Topics Created Using Flare 5

At my DITAbug presentation on Wednesday night, I was asked whether DITA topics created in Flare by exporting Flare's native XHTML to DITA were well-formed or valid. This proved to be a fairly unusual question and it took several phone calls to track down the answer.

The answer, with one caveat, is that the DITA files should be valid per the OASIS DITA DTD. If they are not, there's a bug and the problem should be reported to MadCap. The caveat is that Flare 5 does not support specializations.

An Addition to the Previous Post...

I Forgot...

A tip of the hat to Alvaro in MadCap tech support for clearing up a point about the style properties groups. Thanks...

Notes about Flare’s Style Sheet Editor

Flare’s style sheet editor is very powerful but has several attributes that can be confusing.

One such attribute is the variety of styles, including unusual ones like "generic pseudo-class". Another such attribute is the many properties available for those styles. Another is the combining of the properties into functional groups like Font, Background, or Block, which means that a property can appear in several groups.

This last attribute raises two questions – what do the different functional property groups do? And, if a property appears in several groups, is it the same property each time?

I’ve heard these questions often but never got around to writing anything about them until getting a question (thanks, Jennifer) in a CSS course that I recently taught for MadCap. The question was – “I don't understand the difference between padding in the Box, Cell, and Padding groups in Flare’s stylesheet editor.”

As noted above, MadCap combined many style properties into groups depending on their function. This means that some properties, like Padding, will show up in multiple groups because padding applies to different functions, like paragraph and table cell formatting.

Are the repeated properties simply the same property used in several places? To check, you can list all the properties using the Show: Alphabetical List option on the style sheet editor’s toolbar. If a repeated property is actually the same property, it will show up once in the alphabetical list, exactly what happens with the Padding properties.

Regarding the three functional groups in the question above – Box, Cell, and Padding:

- If you want to format a table cell, use the Cell or Box group properties.

- If you want to format a text paragraph, use the Box or Padding group properties.

Each case, table cell or text paragraph, can be handled by the properties in either of two functional groups, so you'd choose between those groups by finding the one that offered the specific properties you needed. For example, if you want to format a table cell and need to set the margin, select from the Box group. If you didn’t need to set the margin, you could select from either group.

Some Thoughts about “User-Generated Content”

These days, the term “user-generated content” is usually interpreted as content generated by users via mechanisms like blogs, wikis, Twitter, etc. But there’s another way to view the term that I’ve run into recently – content generated by SMEs (subject matter experts) via Word (can also be Frame), to be automatically turned into online help using a tool like Flare or RoboHelp. In other words, an online help project in which the SMEs do the work, with little need for an online help developer after the initial project setup. I’ve run into two such cases in the last three months, both involving Flare.

Both clients wanted to take material written in Word by SMEs and convert it to WebHelp help format. The material changed often – daily in one case – and passing it through a Flare developer was a potential bottleneck. So the idea was to buy Flare and set up the project using the auto-reimport feature. When it was time to generate the output, this feature would check the imported Word file to see if there was a later version and, if so, reimport the new version and regenerate the WebHelp. Could this work?

The answer is yes, with one big caveat. Reimporting the Word file overwrites the results of the previous import. This isn’t a bug; it’s just the nature of a reimport. But the result is that, until the vendors change how their reimport feature works, it means that SMEs can only use features that they can add in Word. Flare-specific features won’t work, and Flare simply becomes an output generator. Why?

Let’s say you import a Word file into Flare and, by breaking the file at the level 1 heads, wind up with ten topics. You then add Flare-specific features, such as links or index entries, to those ten topics, and clean up any bad formatting that crept into the Word file. As it often does…

The problem is that the next time you reimport that Word file into Flare and wind up with new versions of those ten topics, the new topics overwrite those from the prior import and all your Flare-specific features and formatting corrections will be gone. You’ll have to recreate them. This usually isn’t hard, but it’s time-consuming and reduces the automated component of the publishing that the client wanted in the first place. According to MadCap tech support, there’s no workaround to this problem. The nature of a reimport is that it over-writes the topics created in the prior import, period.

So this issue has at least two ramifications if you’re looking for a way to automate the process of creating online help.

First, because the reimport overwrites the topics in Flare and any Flare-specific features added to those topics, all the writing, formatting, linking, indexing, etc. must be done in Word since that’s the only way to guarantee that those features won’t be overwritten. In effect, Flare becomes an output generator rather than an authoring tool.

Second, the overwrite of the topics also means that formatting corrections that you made to the Word file prior to importing it into Flare will be lost; you’ll have to make those corrections again on the next reimport pass. For example, if an SME used local formatting on a table and you had to fix that formatting to get the table to display correctly online, you’ll have to fix that formatting again on the next reimport pass. The only solution to this problem, and it’s far from foolproof, is to get the SMEs to use Word correctly, or at least less incorrectly. Provide them with Word templates, sell them on the idea of using the templates, and teach them how to use the templates correctly.

RoboHelp 8 and DITA

If you use RoboHelp 8, you can start getting your feet wet with DITA without necessarily buying a DITA authoring tool. You can’t create DITA maps or topics – that capability won’t be available until, presumably, RoboHelp 9. But you can import DITA maps and topics into RoboHelp 8 to see how well it handles DITA features and how well it turns the DITA material into outputs like WebHelp.

The sticking point is that RoboHelp 8 uses the DITA Open Toolkit (OT) to import DITA material. This means you need the properly configured OT on your PC. If you typically work in RoboHelp’s GUI, installing and configuring the OT will be far more techie than you’re used to. The instructions below should help make the process easier. (Note that some version numbers may have changed since I wrote this. In particular, v. 1.4.3 may have been replaced by v. 1.5.)

Download and unzip the OT from:

http://sourceforge.net/projects/dita-ot/files/#

This will create, among other things, a folder called doc that contains the installation instructions.

Then, if you’re a Windows user, follow the instructions at:

C:\ditaot\DITA-OT 1.4.3\doc\ installguide\windows_installing.html

A crucial step is to be sure your environment variables are correct. You’ll know if they aren’t if you try to import a DITA map into RoboHelp and get this message (shortened somewhat here) in RoboHelp’s Output View pane:

C:\DITA-OT1.5\build_preprocess.xml:269: java.lang.VerifyError: (class: topicpull, method: …
...
Inconsistent stack height 1 != 0

Again, this probably means your environment variables aren’t set correctly. To fix them, follow the instructions in the document at:

C:\ditaot\DITA-OT 1.4.3\doc\installguide\ windows_settingenvvariables.html

However, be aware that some of the settings needed for your PC, particularly the JAVA_HOME setting for the folder where you installed the JDK, may differ from those in the setup instructions.

Note also that some environment variables are optional. For example, if you do not plan to output JavaHelp, you can ignore the JHHOME setting. If you do not plan to use the Apache FOP, you can ignore that setting for the CLASSPATH variable. Ditto for the Xalan setting for the CLASSPATH variable.

Note also that some of these settings are long and complex enough that you do not want to type them if you can avoid it. An easier thing to do is to open the environment variable instructions file (… windows_settingenvvariables.html), copy the value of each variable field that you’re modifying and paste it into Notepad, copy the value to be added for that field from the instructions in the …windows_settingenvvariables.html file, and paste it into the code in Notepad, and finally copy the code out of Notepad and paste it into the appropriate variable field. As messy as this sounds at first, it’s actually straightforward with less risk of typographic errors.

Finally, note that I'm not getting into the specifics of variable settings, especially for the JDK, since it will vary depending on which version you have. But email me if you have specific questions and I'll try to answer them.

You’ll know that you’ve set all the environment variables correctly if you try to import a DITA map and get the “import successful” message in RoboHelp’s Output View pane.

How long will this take? If you’re accustomed to commonly working at this level of technical detail, about an hour. If you’re not, plan on two to three hours. This may be a big chunk of time in a crowded schedule, but it’s a small investment in time that can open up a whole new feature set in RoboHelp.

If you’re interested in more information about how help authoring tools (HATs) are starting to support DITA, I’m giving two presentations at Lavacon in New Orleans in late October, one on how to use HATs to work with DITA and one on how to use HATs to create simulated CMSs. If you’re not going to Lavacon, I’d be happy to send you copies of the PowerPoint slides after October 30.