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.
Kevin wondered how to answer a request from a colleague: <<"What I am
really looking for is a way to create customized versions of the
documentation that the Tech Pubs and Marketing groups already
create/maintain while being able add, delete, modify, and augment said
content. This will allow us to deliver custom documentation for
professional services engagements that target the organization's
specific environment and needs. This would make keeping up-to-date with
documentation updates and changes much easier on my end...">>
I'd be very wary about giving others the opportunity to mess around
with my docs, particularly in a situation where the docs must be
updated and recustomized. It's hard enough for us to make sure all the
relevant links are present and correct, not to mention all the other
"is anything missing?" checks that we do--I can't imagine someone
unfamiliar with the documentation trying to do this and doing a good
job, particularly if (a) they're not as neurotic about quality as we
are and (b) they're in the usual time crunch situation and take
shortcuts to meet deadlines.
My first thought is that the actual solution you're looking for is
trivial: a customized table of contents (or "portal") that focuses on
each client's specific needs. The corpus of the documentation remains
identical for all customers, but those who need something customized
get a table of contents that meets their unique needs by directing them
quickly to the things they need to know. Better still, design your
documents to include _two_ TOCs: a general, "for everyone", TOC, and a
"placeholder" page where you can insert a custom TOC and recompile the
file. In the absence of any customization, the placeholder could be
simply deleted or redirected to the general TOC.
This has several advantages. First and most important, it keeps control
of the documentation in the hands of those who are best suited to
control it (i.e., you and your fellow writers). Second, it's far easier
to create a custom TOC than it is to do what is effectively database
publishing (i.e., pulling content out of a database to generate the
final document) without a database optimized for this function. Third,
it lets you maintain (i.e., provide customer support for) only a single
set of documentation rather than (in the extreme case) one set per
customer. Third, if your colleague guesses wrong about what the client
really needs, then the client still has access to the complete
documentation set via the general table of contents and index.
Each of these objections could be overcome with a bit of work, but
someone has to take responsibility for doing it. The quality control
issue is, to me, the most serious one. People who want quick, one-click
solutions almost inevitably lack the time (or patience or desire) to
make sure they've done the job right. That could lead to serious
problems. As they say, "the road to Help is paved with good
intentions". <gdr>
<<"Ideally, it would be possible for the customer to add their own
work product to this electronic version once it is delivered so that
they could store all information related to their implementation in
one place.">>
I'm not up on the latest Help technologies, so someone else (Char?)
should answer this, but isn't it possible to annotate Help files to
include your own notes, exceptions, and additions? If so, that's
probably the optimal solution because it builds on an existing
technology. Beyond this, I'm not comfortable with letting end-users
modify my documentation. I've simply seen far too many egregious errors
introduced by otherwise intelligent individuals during doc reviews.
WebWorks ePublisher Pro for Word features support for every major Help
format plus PDF, HTML and more. Flexible, precise, and efficient content
delivery. Try it today!. http://www.webworks.com/techwr-l
Doc-To-Help includes a one-click RoboHelp project converter. It's that easy. Watch the demo at http://www.DocToHelp.com/TechwrlList
