Looking for re-packaging publishing app?

Subject: Looking for re-packaging publishing app?
From: Geoff Hart <ghart -at- videotron -dot- ca>
To: TECHWR-L <techwr-l -at- lists -dot- techwr-l -dot- com>, mlist -at- safenet-inc -dot- com
Date: Tue, 09 May 2006 08:58:04 -0400

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.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --
Geoff Hart ghart -at- videotron -dot- ca
(try geoffhart -at- mac -dot- com if you don't get a reply)
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -


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

You are currently subscribed to TECHWR-L as archive -at- infoinfocus -dot- com -dot-
To unsubscribe send a blank email to techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit http://lists.techwr-l.com/mailman/options/techwr-l/archive%40infoinfocus.com

To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com

Send administrative questions to lisa -at- techwr-l -dot- com -dot- Visit
http://www.techwr-l.com/techwhirl/ for more resources and info.

Looking for re-packaging publishing app: From: mlist

Previous by Author: Misc: New phishing scam trick (take II)
Next by Author: Tools: Translation and pronunciation
Previous by Thread: Looking for re-packaging publishing app
Next by Thread: RE: Looking for re-packaging publishing app

What this post helpful? Share it with friends and colleagues:

Sponsored Ads