Re: Online customizable documentation

Subject: Re: Online customizable documentation
From: "Mark Baker" <mbaker -at- omnimark -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Thu, 13 Jan 2000 16:37:53 -0500

Darren Barefoot wrote

> Many of our clients customize their interface - user-defined field labels,
> different dialog box names, different error messages, etc. We allow them
> 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
> 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>

I generally don't like embedding code into data. It makes it very difficult
to validate the data or the code and it makes it very difficult for other
processing applications to use the data.

My approach would be to do something like this:

> Entering a <term "PunchList"> Item</H1>

and then let the processing application figure out how to look up this term.

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

This is a fundamental problem. You can't index a document until its content
is determined. It is no use indexing the data used to generate the content.
Indexing only makes sense once the document has been generated.

You can do one of 2 things:

1. Don't index. Indexing is just a primitive means of providing custom
navigation of information. Generating information on the fly is a more
sophisticated approach, which, if done properly, removes the need for
indexing. (But, of course, just substituting terms isn't going to achieve

2. Have the customization process generate a static document which is then
indexed. This is the best solution if the material is customized rarely. It
won't work so well if customization occurs every time someone access the

You could implement solution 2 just as I described before, having an
OmniMark program generate the appropriate help markup and call the help
compiler to create the file you deliver to the customer.

Previous by Author: Re: customizable documentation
Next by Author: Re: Indexing dynamic text?
Previous by Thread: Online customizable documentation
Next by Thread: RE: Vugraph? Viewgraph? Summary

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

Sponsored Ads

Sponsored Ads