Thursday, November 30, 2017

Imagine that you’re on an oil platform in the North Sea.
Strain gauges in a drill tube detect metal fatigue and automatically start the
process of replacing the tube.

Or imagine that you’re looking at an exhibit in a museum.
Your smartphone knows which exhibit you’re at and automatically describes it. Move
to the next exhibit; your phone automatically tells you about that one. Your
phone also knows that it’s noon and suggests lunch. It also knows that it’s
Friday, when the cafeteria offers a favorite dish of yours until 1 PM, and
mentions that as an inducement.

Or imagine other scenarios where a computer can take action
or offer information or assistance based on some context. That’s a large part
of what Industry 4.0 and Information 4.0 offer. In this article, I’ll look at both
but focus on Information 4.0 as being of primary interest to technical
communicators.

For industry, Industry 4.0 is most important. And, as Adobe’s
Stefan Gentz noted in a conversation with me at TCUK, what industry needs now
is standards, protocols, and use cases.

Technical communicators are unlikely to create those
standards, protocols, and use cases but we may be involved in documenting them.
Doing so will call for familiarity with a vast range of new technologies.

Furthermore, we’re likely to use those technologies to document
things outside the bounds of Industry 4.0. That will change technical
communication the way word-processing did in the early 1980s and HTML in the late
1990s. That broad applicability of Information 4.0 is why it’s the focus of this
article.

Characteristics of Information 4.0

Its evangelists postulate that Information 4.0 content will
have six primary characteristics.

Molecular – Replaces documents with “information
molecules” that can assemble themselves into “compounds” based on a “state
vector”.

Dynamic – The context may change so the
information molecules must change too.

Offered rather than delivered – Information is
available as needed but not pushed on the users. (Think of a dynamic help
system that’s always available but discretely tucked into a corner of the
screen.) Also, because it’s hard to predict what information users might need
and whether users have the background knowledge needed to understand a
particular molecule, we may need to create different molecules containing
different versions of the information.

Ubiquitous – Information has to be available
everywhere, and has to be searchable.

Spontaneous – Information has to display based
on the context of the information requests.

Profiled automatically – Information has to fit
user’s needs as closely as possible rather than being generic.

Are these characteristics implementable today? Here are some
of the issues.

Molecular

Think of molecular content as topic-based authoring taken to
extremes. “Fragments” of information are available at any given moment to fit the
context of requests for information. This will boost the number of files.

But as the number of files increases, so do the hardware and
software requirements – more RAM, faster hard disks, and faster networks. Can your
tools and networks cope with huge numbers of files or will you have to upgrade your
hardware or tools, or change tools? (And the definition of “huge” is
subjective. I meet many people who have five-hundred files in a Flare project
and consider that huge. The largest I’ve ever worked on had 176,500 files. The
largest I know of is close to 900,000.)

As the number of files in a project grows, so does the need
for project management rigor. The need for a project description becomes
crucial. Even simple things like file naming conventions have to be defined and
followed with no deviation. Without these and similar steps, the work may go out
of control.

Assembly into compounds will make extensive use of metadata.
Current tools offer some metadata, like conditional build tags, but the Information
4.0 metadata will have to be open source, such as RDF. That will add a new and
unfamiliar requirement for authoring.

The “state vector” that drives the assembly process is a set
of temporary context-states – an advanced form of today’s context-sensitivity. Somebody
or something will have to define and
maintain them.

Is it feasible today?
Yes, in a limited way. Today’s tools support topic-based and fragment
authoring, but not in the numbers needed by Information 4.0. Also, molecules
and fragments created by today’s tools are meant to be combined into one output
rather than live on their own. That may change how we create those molecules
and may lead to machine-created content and AI.

Dynamic

The molecules will have to be continuously updated to match
changing state vectors, effectively in real-time. Furthermore, the molecules
will have to be in open databases rather than stored on authors’ local PCs. It
also means that compilation becomes a bottleneck in some cases because users
may not want to wait out the compilation time, just as users don’t want to wait
out slow-leading web sites today.

We’ll also need fast, reliable network access to send the
context state to the processor and the updated molecules back to the user
quickly. There will also need to be some local storage for situations where
network access is slow or nonexistent.

Is it feasible today?
Yes, in a limited way. Current tools are starting to let us metatag content but
that’s still in an early stage. Current tools will also have to create
fragments that don’t contain tool-specific codes that may not work in an open
standard environment. (MadCap Flare does this with its Clean XHTML output.) Our
tools will also need to support local storage.

Offered Rather Than Delivered

Breaking information into the smallest possible molecules.
However, defining the parameters of those molecules and creating them using
traditional writing methods may not be fast enough. We may need machine-generated
content.

Is it feasible today?
Yes, in a limited way. The biggest bottleneck is the need to create molecules
rapidly enough.

Ubiquitous

The molecules have to be available from anywhere and
searchable. HTML5’s responsive design allows ubiquity across multiple devices
and platforms. SEO (search engine optimization) increases searchability and findability.
However, the need for ubiquity and findability rules out hard-copy outputs, perhaps
even PDF. This will be a wrenching move for many companies today.

Is it feasible today?
Yes, to a surprising degree. Responsive design lets us create one output that
runs on multiple devices rather than having to create one output for each device.
But the compilation time may be longer than users are willing to wait.

Spontaneous

The “contexts” that trigger spontaneity are more advanced forms
of today’s context-sensitive help. They might include device orientation (how
users hold the device), location detection, external states like temperature,
and more. The contexts have to be sent to the processor to let it alter the
information to fit the context. This requires methods of context detection, metadata
(again), plus fast networks to get the new content back to the user fast enough
to make it useful.

Is it feasible today?
Yes, in a limited way. We’ve been creating context-sensitive help since the
dawn of online help. What we don’t have in the technical communication world is
the spontaneous side, where information might change dynamically as the context
changes. For that, we have to look to the web and mobile app worlds. Once
online help went from RTF to HTML in 1997, technologies from those worlds have
been available to technical communication projects but I’ve almost never seen
them used.

Profiled Automatically

User profiling will be done automatically based on the
context, again requiring major and continuous use of analytics.

Is it feasible today?
Yes, in a limited way. We’ve been able to create targeted online help for years
using conditional build tags and placeholders like variables and snippets. The
problem is that we can’t create the output dynamically. Instead, we generate a
fixed output for user A. To create an output for user B, we change the
conditions and placeholder values and regenerate, which adds a delay. Our
online help projects have offered search capabilities for years but I rarely
encounter companies that save and use the search data. I have never encountered
a company that uses that search data to automatically update and regenerate the
material. (If your company does, please contact me.)

How Will It Affect Tech Comm?

Here are some of the more obvious likely effects.

Writing

We won’t write documents. Instead, we’ll do
single sourcing with a twist – creating information molecules that can stand on
their own as well as being combined into larger outputs. This may affect users
of document-oriented tools like Word and FrameMaker the most. (We can use those tools to create molecules
– e.g. topics – but many authors will find true topic-focused tools to be more
convenient.)

No more traditional continuity – e.g. no more
writing “as described above” because “above” may now be in a separate molecule.

No more local formatting since local formatting
will probably break automated processing tools that look for styles.

The need to structure content organizationally, using
templates, but also semantically using metadata.

Dealing with dynamic wording. We say “click the
button” when writing for large screens but “tap the button” when writing for
mobile. What do we do when using responsive output to that runs on both large
screens and mobile devices? One answer today is to use an intermediate word like
“select” but that doesn’t ring true to desktop or mobile output. There are ways
to alter wording dynamically using CSS, which should spread as more authors start
creating responsive output but they’ll have to work in the code until our tool
vendors start to support it. Which will call for greater facility with…

Technology

We’ll need more technical skill. We’ll have to
be familiar with, or more familiar with, metadata, CSS, networks, and the other
technical communication technologies mentioned above.

We’ll need familiarity with technologies and
standards from outside technical communication, like iiRDS and RDF.

We’ll need to follow good coding practices and
standards.

We’ll need up-to-date tools.

And we’ll need formal training in how to use
those standards and tools. Peer-to-peer training is common but too often simply
passes bad practices on from one generation to the next.

Corporate Role

Nobody cares about “documentation”, but
“content” is cool, possibly even a revenue generator and/or a branding mechanism.
This may help technical communicators become more of a force within the company
by changing the company’s perception of tech comm.

We have to stop trying to block new technologies
in technical communication. Someone in an audience once responded to my
discussion of social media by saying “over my dead body.” The technology will
still go ahead, but around her, as her career has dead-ended.

Four Major Issues on the Business Side

You may be thinking that all this sounds interesting, with
the promise of challenging work and new lines of work. But Information 4.0 will
have to overcome four business hurdles.

Does it support my company’s strategic and
business direction? If it does not do so, in ways that are clearly and
quantitatively demonstrable, it either won’t be funded at all or will be a quickly-forgotten
one-off.

Does it have high-level management support? Even
if Information 4.0 supports the company’s strategy and business, other
initiatives within the company probably do as well. Only the ones that get
management support will survive, or at least have a chance to survive.

Does company culture support this higher technical
complexity? The answer is often no. Trying to force Information 4.0 into an
unsupportive culture will cause turnover in the documentation groups; you’ll
get people who are comfortable with the technology but lose people who have the
experience and the institutional memory.

Are goals and terms clearly defined within my
company? As silly as this sounds, it’s very possible that people in your
company, especially management, may not understand the terms we take for
granted. They may also not have any clearly defined goals for an Information
4.0 initiative. Any Information 4.0 initiative is going to require an
educational component on your part.

Summary

Much of Information 4.0 still conceptual, but it represents
a continued increase in the technical side of technical communication, and
offers multiple paths forward for tech comm in the years ahead. It’s worth
watching.

Thursday, November 9, 2017

On November 1, I put up a post about best practices for using MadCap Flare. The post included some tips from Craig Wright of StrayGoat Writing Services , but I didn't include his contact information. Sorry about that.

Wednesday, November 8, 2017

I was asked on LinkedIn whether Flaresupported image maps and how to create them. I don't see image maps used much anymore but they can be useful. Flare makes it easy to create them with its built-in image map editor. Here's how:

Insert your graphic in the topic.

Right-click on the graphic and select Image Map from the dropdown menu.

Click on any of the three "New... Mode" buttons on the toolbar and draw the desired shape. To resize a shape, click on and drag one of its drag handles. To move a shape, just drag it. There are various other image options, but the three mode buttons are the core.

After you create the shape, double-click it. The Area Properties dialog box opens. (It's basically the same as the Hyperlink Properties dialog box.)

Specify the link parameters like you would for any type of link and you're done.

Be sure to test the hot spots in your browsers. I haven't used image maps in a while so there may have been some changes in the browsers that break the hot spots, but they did work fine on my PC using Chrome, IE, and Edge.

Wednesday, November 1, 2017

Flare has so many options that it can be hard to decide where
to start, even if you've taken a class and especially if you haven't. New Flare
users often just jump in. But this can get you off to an inefficient start,
perhaps even a bad start, and create problems that ripple down to later
projects.

In this post, I’ll take the topic of
best practices further by expanding on the Standards section of the white
paper. The original MadBlog post, the white paper, and this blog post are based
on twelve years as a certified Flare consultant and trainer and eighteen years
of hypertext consulting and training pre-Flare. However, always consider your specific situation before following any
suggestions. With that, let's look at the standards issue in more detail.

The more you standardize, the more
consistent your projects will be and the less authors will have to guess about
what setting to use for a given task or feature. Things you might standardize
include:

Graphic file formats – Many graphic formats are available
today and Flare supports most or all the ones that you’re likely to use. The
traditional approach is to use GIF for screen shots and JPG for photos. This
works but you’re maintaining two sets of files, GIF and JPG.

You may find it more efficient to use PNG for all graphics, including those for
your print outputs. A PNG’s quality may not be as good as that of an EPS but
your users won’t know because they haven’t seen the EPS so they won’t have anything
to which to compare the PNG.

Conditional build tag usage – Condition tags are
the core single sourcing feature but they can go out of control if you don’t
set rules for their use. (I’ve talked to two firms this year that used tags with
no initial rules about when to insert and how to call them. One company had a
project with about 1,000 topics and 1,500 “unruly” tags. The other had about
1,000 topics and 15,000(!) such tags. The result was that new authors couldn’t
figure out what tags to include or exclude for a given target and when to add
new tags.)

Creating and inserting tags is flexible – you can apply tags to a character in
a topic, a paragraph, an entire topic, a group of topics, a folder, and any
other element in a Flare project. And it’s easy – assign a name, pick a color,
add an optional comment, and you’re done. In fact, it’s so easy that new authors
often gloss over the crucial first step – defining what they’re trying to do
and documenting it. So my suggestion is to first decide what you want to do,
then define rules for inserting and using the tags, such as the smallest
element you can tag. Document this. And test the results to make sure you’re
getting what you expect.

“Try to plan your content reuse at an early stage, especially if there are
multiple writers involved. It’s no good creating snippets if the other authors
aren’t aware of them.”

and

“Make sure your snippets are well organized. If authors struggle to find the snippets they need, they may create their own and duplicate existing content.”

A few comments of my own regarding Craig’s points:

oGet all authors involved in the planning early
on.oDefine the variables and snippets in two groups
– project-specific and shared.oSet up a parent/child project structure using
the Flare Project Import feature and put shared variables and snippets in the
parent project for easy downloading to the child projects.oLet all authors know when a new variable or
snippet has been added to the shared sets.oMake sure that all authors know that any changes
to shared variables or snippets must be made by the “owner” of those files, not
by the individual authors.o Make sure that the snippets are clearly named.

Index entries – My experience is that
traditional indexing is declining among Flare authors, with search taking over.
This makes sense since search is easier to implement, but an index can do
things that a search can’t. For example, if I refer in a topic to a sandwich
made of cold cuts on a tubular loaf of bread as a “sub”, searching for “hoagie”
won’t find the topic because the search is looking for the search term in the
topic text. But an index lists keywords attached
to the topics rather than terms in the topics, so it’s easy to add the
keyword “sub”, plus the keyword “hoagie, see sub”, and so on. This makes it
more likely that users will find the right topic. (Flare does let you add
search synonyms but this can be a tedious job.)

If you’re going to create indexes, define some rules to make the entries
structurally consistent from project to project. Here are a few:

oDecide if the verb should use the infinitive
(“to print”, then remove the “to”, leaving “print”), or the gerund
(“printing”). I prefer the infinitive but that’s up to you.oDecide whether the noun should be plural
(“documents”) or singular (“document”).oDecide whether to use sub-entries. For example,
the term “BBQ” might be a first-level index entry, with “Carolina”,
“Tennessee”, and “Texas” as sub-entries. Note that you could also use those
sub-entries as first-level entries – e.g. “Carolina BBQ”, “Tennessee BBQ”, and
so on.oConsider using inversing. If you include the
first-level entry “print dialog box”, include “dialog box” as a first-level
entry with “print” as a sub-entry below it.

Hyperlinks vs. cross-references (xrefs) –
Hyperlinks have been with us since the beginning of online help but they have
two limitations.

oThe link text doesn’t update if the title of the
target topic changes. Let’s say you link the term “sub” in topic A to the
“Subs” topic. You then change the title of the “Subs” topic to “Hoagies”. But
the link term remains “sub”. You must find and change it by hand. In contract,
a cross-referenced term is programmatically linked to the title of the target
topic, so changing the target topic’s title automatically changes the link term
too.oA hyperlink keeps the format of a hyperlink when
you output to print, such as PDF, and the link works if the user is viewing the
material on the screen. But when the user prints the material, the link
obviously doesn’t work. But a cross-reference will literally change its format
from a link style to a page reference – “information about spaniels, see page
225”.

So a cross-reference is a better
choice if you generate online and print targets. The limitation is that a
cross-reference won’t work if you create a link from a topic in a target to an
external file, like a URL or PDF. In that case, you must use hyperlinks. That
limitation aside, cross-references are the best and most flexible choice for
links.

File naming – Setting file naming conventions
is, surprisingly, one of the hardest tasks in working with Flare. There are two
naming issues, programmatic (thanks to Stephanie M.), and semantic.

oProgrammatic conventions are straightforward. Use
all lower case or mixed case? Can multi-word file names use spaces, use
underscores in place of spaces (file_name), or use “Camel Case” (FileName).
Check with your IT department.oSemantic naming conventions, to indicate what a
file contains, is harder, and you’ll want to involve all the authors in the
process. For example, you might decide to name graphic files by the name of the
screen followed by the type of screen, such as “Dialog Box.” The result is
“Print Dialog Box”, easy to find in a list if you know the name of the screen
that you want. Alternatively, you could name graphics by the type of screen
followed by the name of the screen, such as “Dialog Box – Print”, easy to find
in a list if you know that the desired screen is a dialog box but don’t
remember which one.

Two final planning thoughts in addition to documenting your
standards, getting trained, joining a user group, and contacting support as
discussed in the white paper:

Decide what your priority and secondary output
targets are. Some features, like togglers, work fine online but not in print.
So deciding on your priority target will help guide your selection of Flare
features.

Decide if mobile is in your future. If it is,
note that some features, like popups, don’t work on mobile devices. So knowing
if you’re going mobile will also help guide your selection of features. Note
that this can apply in other project areas as well, such as making sure that
all movies you create using Mimic are in HTML5 format because SWF format won’t
display on iOS devices.

Conclusion

I’ll partly repeat what I said at the end of the white paper
– Flare is a big powerful tool. If you’re new to it, it may not be obvious what
can even be standardized. By following the suggestions in the white paper and
here, you’ll help get your Flare work off on a sound footing and help keep it that
way.