Online customizable documentation

[Darren Barefoot <dbarefoot -at- mpsbc -dot- com>]

Good afternoon,

We're confronted with a similar problem, except that it pertains to online
help systems:

Many of our clients customize their interface - user-defined field labels,
different dialog box names, different error messages, etc. We allow them to
do this via a language database that ships with the program. For our next
online help system (WebHelp or HTMLHelp), we'd like each interface element
in our help system to reference this language database, and then dynamically
display the correct content. So, this content:

  <H1>
   Entering a Punch List Item</H1>
  <P>
   <B>To enter a punch list item</B></P>

Becomes

  <H1>
   Entering a <%=HelpLangMan.LanguageString("db.PunchList")%> Item</H1>
  <P>
   <B>To enter a <%=HelpLangMan.LanguageString("db.PunchList")%>
item</B></P>

The problem is: How do we handle indexing and full-text searches? Obviously
these bits of code won't index very well, and the full-text search will just
be a big mess. Any advice you've got would be appreciated. Thanks. DB.


-----Original Message-----
From: Mark Baker [mailto:mbaker -at- omnimark -dot- com]
Sent: Thursday, January 13, 2000 8:52 AM
To: TECHWR-L
Subject: Re: customizable documentation


Philomena Hoopes wrote


> One of our customers, having received their first documentation in PDF
> format, proceeded to ask whether they could have editable files.
> Specifically, they want to change the references to system-assigned field
> names, substituting their customized names.

I experimented many years ago with a program that could be distributed to
customers who bought highly customizable telephone sets. The idea was that
they would use the program to enter how their telephone sets were programmed
and then push a button and have custom user guides printed from their office
printer. The prototype worked fine, but it wan never developed.

This is how I would do it today:

Store the documents in either in a database or in some form of markup (XML
or SGML).

Write a web application in OmniMark that would take the customization
information from the user, query the database or parse the markup, and
prepare a customized version in XML form.

Next, depending on the user's selection, the OmniMark program would either
generate an HTML page with the customized information included, or generate
a TeX file call out to TeX to produce PostScript or PDF to deliver to the
customer. This file would be sent back to the customer via their browser.

This way, you give the user the ability to do the customization they need,
you don't give them source files, and you ensure that your corporate
standards are met in all documentation that bears your company name. This
method will also be easier for the customer use, and less error prone, than
having to edit the files themselves.


---
Mark Baker
Senior Technical Communicator
OmniMark Technologies Corporation
1400 Blair Place
Ottawa, Ontario
Canada, K1J 9B8
Phone: 613-745-4242
Fax: 613-745-5560
Email mbaker -at- omnimark -dot- com
Web: http://www.omnimark.com



^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Sponsored by Weisner Associates Inc., Online Information Services
Training & consulting for RoboHELP, Dreamweaver, HTML, and HTML-Based Help.
More info at http://www.weisner.com/train/ or mailto:training -at- weisner -dot- com -dot- 

Sponsored by 4Translation.com, Language Translation Simplified. Instant 
on line quotations and free samples available for technical documentation.
http://www.4translation.com  Any File...Any Language...Anytime

---
You are currently subscribed to techwr-l as: dbarefoot -at- MPSBC -dot- COM
To unsubscribe send a blank email to leave-techwr-l-9978K -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.