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.
Brian Das reports a challenge: <<... our clients operate in a heavily
regulated environment. The regulatory body demands that our clients
communicate their day-to-day transactions... with XML. We've customized our
software... as the regulations change. But the clients are completely
baffled and frustrated by the whole regulatory environment, and how the
software works in it. They don't get the concepts, including the underlying
technology (XML). So they can't even begin to understand how those concepts
function "on the ground" (i.e. in the software).>>
Can't help with the regulatory part, but it seems to me that this is a
solution tailor-made for a "wizard" of some sort. The nice thing about XML
and other structured languages is that they chunk information nicely, and
once you've got it chunked, moving the chunks into the right bureaucratic
pigeonholes is the easy part.
Have you considered developing a very simple "map" tool that lets customers
map their data (i.e., the XML chunks) to the pigeonholes required by the
legislation? This could take the form of a series of templates (e.g., one
for each regulation), followed by a pick list of customer data (generated by
your application). The user would simply drag the names of XML entities from
their data (tagged with user-friendly names) onto the template to establish
a correspondence (map) between their information and the regulatory
information. Once done, the software does the rest of the job: creating the
XML output.
On second thought, maybe I can help with the regulatory part. Your
developers really need to get in touch with the regulators so they can
figure out how the regulations are developed and updated. Knowing this is
the only way for them to address the root of the problems your customers
face. Think of it this way: you can't develop a product to solve someone's
problem until you understand the problem.
<<Documentation (me) is constantly throwing together ad-hoc, fire-fighting
documents for free to help a handful of clients out of a jam each time
regulations change.>>
This is a classic sign that the software doesn't meet user needs, and it's
not something you can fix by documenting it better, as you've already
noticed. My proposed solution becomes an easy sell from a marketing
standpoint: "Remember the bad old days, when you had to wait for Brian to
write you an explanation of how to do it? XMLMangler 2.0, available now,
eliminates that wait by providing a simple method of dragging your data into
into the regulatory forms. Call now to learn about how much time we can save
you. Brian's mom would be real grateful." <g>
<<First, I want to recommend a handful of mini-tutorials (delivered online
somehow) that illustrate the concepts>>
Is it possible to spend a day or two looking over the ad hoc documents
you've created over the past year? These should reveal patterns in the
problems, and thus, typical solutions. (You noted that "These concepts won't
change much over time", suggesting that you've already partially identified
the path a wizard-based approach should take.) This should form the basis of
your tutorials.
But don't forget: you can lead a user to the tutorial, but you can't force
them to think. Some will indeed learn from your tutorials, but others will
be happier to follow the established path of calling your tech. support
people instead. Build the tech. support into the product and those calls
will go away. After all, what do the tech. support people do? They ask
questions (just like a wizard), then move to the next question (step 2 in
the wizard), then move the the next question (step 3), and so on, until they
walk the user through to the end of the process.
<<But the rest of the information -- the tactical, click-by-click stuff that
changes every few weeks as regulations change -- seems to be a maintenance
nightmare in the making.>>
If the regulations really change weekly, you have a maintenance problem no
matter what approach you take. Perhaps the simplest solution is to assign
someone (one of your developers?) the responsibility of updating the
templates, and either consider this person's time as a fixed cost of doing
business or as a value-added service you can bill for. Turn a problem into
an opportunity! Moreover, this is another strong reason to talk to the
regulators. Their goal is to get information quickly and efficiently so they
can confirm compliance. Your goal is to help them get that information. See
the overlap in your respective needs?
<<I'd like to deliver it in a kind of knowledge base... Informal "articles",
planned by me but written by subject matter experts around the company,
added to our support Web page.>>
Knowledge bases work very well for a particular type of user (someone who
wants to learn by themselves and who is patient enough to root through your
knowledge base). But most users just want to get the job done, and can't be
bothered digging through a knowledge base to find solutions. (For evidence,
check the techwr-l archives for a rough tally of the number of people who
ask questions that could be solved by--say--a trip to the Microsoft
knowledge base or a search of the techwr-l archives. That's not intended as
a criticism of these people, but rather as a demonstration that learning
styles and problem-solving needs differ.)
I also have concerns about asking the SMEs to write the articles. Many of
them will simply lack the skills to write well, and those who do write well
may have too many other demands on their time to do the work. At a minimum,
someone needs to do quality control on the material added to the knowledge
base; ideally, it should be created by a skilled writer in the first place,
then reviewed by the SMEs. Do you really want to create the precedent that
"we don't need Brian to create our documentation"?
<<In time, super-users with whom we have good relationships could also write
some articles. (I've been told these super-users are happy to share their
knowledge...)>>
A better use of their time might be to work with them to figure out how they
became super-users. Some are just geeks like us, and love tinkering and
getting better at the technology. But a few may have discovered,
accidentally or otherwise, some "unifying metaphor" for how to understand
the software. Your job would be to identify what they know, then present it
effectively... whether in a knowledge base, or embedded directly in how the
software works.
--Geoff Hart, geoff-h -at- mtl -dot- feric -dot- ca
Forest Engineering Research Institute of Canada
580 boul. St-Jean
Pointe-Claire, Que., H9R 3J9 Canada
"Work is of two kinds: first, altering the position of matter at or near the
earth's surface relative to other matter; second, telling other people to do
so. The first is unpleasant and ill-paid; the second is pleasant and highly
paid."--Bertrand Russell
---
You are currently subscribed to techwr-l as:
archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot- Visit http://www.raycomm.com/techwhirl/ for more resources and info.
