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've been asked to recommend solutions to a documentation problem, and I'm
hoping you whirlers can help me by picking apart my ideas.
About half of our clients operate in a heavily regulated environment. The
regulatory body demands that our clients communicate their day-to-day
transactions to the regulatory body with XML. We've customized our software
for those clients, and continue to do so (for a fee) 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).
As a result, the company is getting rocked on several fronts. Support is
lead by a real softie who won't say no or ask for money whenever a panicked
client calls for help. Same with data conversion people -- they're spending
countless hours scrubbing and fixing corrupt data. 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. The
company emails these docs to clients, and then....well, who knows what
happens to them after that?
I'm just starting to put together my recommendations to solve the
documentation problem, and I wanted some feedback.
First, I want to recommend a handful of mini-tutorials (delivered online
somehow) that illustrate the concepts. Using diagrams and a conversational
tone, I want these docs to teach the concepts that clients need to
understand before they can start to solve their own problems. These concepts
won't change much over time, so I'm pretty sure it will be worth the effort
to develop the content.
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.
So I'd like to deliver it in a kind of knowledge base. Here's what I mean by
knowledge base: Informal "articles", planned by me but written by subject
matter experts around the company, added to our support Web page.
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 with other client on the phone, but are limited because the
knowledgeable clients aren't likely to have free time at the exact moment a
struggling client needs it. So I think there would be some willingness among
clients to write a few hundred words...)
Essentially, I'm hoping that by moving the writing effort around the company
and putting the results on the Web, with me in a planning & editorial role,
the knowledge will get out there faster amd be more readily available.
Given this high-level overview of the situation, what do you think? Please
shoot as many holes as possible in the idea, so I can either scrap it or
improve it. Thanks for your ideas!
Cheers,
Brian
_________________________________________________________________
Get Hotmail on your mobile phone http://www.msn.co.uk/msnmobile
---
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.
