Customizable docs?

Subject: Customizable docs?
From: "Geoff Hart" <geoff-h -at- mtl -dot- feric -dot- ca>
To: TECHWR-L -at- lists -dot- raycomm -dot- com
Date: Thu, 13 Jan 2000 09:28:12 -0500

Philomena Hoopes reported that <<One of our customers...
[asked] whether they could have editable files... they want to
change the references to system-assigned field names,
substituting their customized names... how can documents be set
up to allow each customer to adapt their own documentation?>>

I assume this isn't just database software, where customers get to
build their own databases and name the rows and columns
whatever they feel like naming them? If that's the case, pick up any
good database manual to see how they handle this sort of thing.
Guides to programming languages might provide another type of
solution for situations in which the underlying engine remains the
same, but customers can combine the functional elements very
flexibly. On the assumption this is something like a point-of-sales
terminal, where customers mostly want to change the company
name that appears on the splash screen or the names of the
technical support staff:

One obvious approach might be to use some form of conditional
text or lookup table to tag the parts that you let customers change.
For example, just about any word processor's mail merge feature
would do the job nicely; all the customer would have to do is
change the text for the field names in the merge file, and combine
that with the main document to generate the final, merged
(customized) document. There are undoubtedly more sophisticated
ways to do this, such as SGML or XML, but I don't know enough
about how to implement such a solution; if you explain your writing
software and how you produce the docs, someone on techwr-l can
almost certainly provide details.

<<What are the long range maintenance implications?>>

I'm uncomfortable with the idea of turning docs over to customers
with no way for me to review what gets done to them; liability
disclaimers notwithstanding, this is the equivalent of giving a
loaded handgun to a young child and telling the kid not to point it at
anyone. Pardon me for overdramatizing to make a point; the reality
is far less sinister. Just think of the last-minute production
problems you've heard about on techwr-l (or experience yourself)
and you'll see the kind of problems that could develop. Can't you
imagine your technical support people? "I'm sorry... which field did
you say? There's no such field in the software, Sir." Worse yet:
"What do you mean the chapter on printing is missing from the
manual? It's right here in the printed copy I've got. Are you sure you
didn't pirate our software and screw up when you photocopied the

OK, enough of the contrarian viewpoint. This can certainly be done,
and done well, but like any other process, you'll have to try it out
with a customer first to see where the pitfalls lie. Think of this as
beta testing your documentation: you'll discover some of the
problems a typical customer would encounter while customizing,
and figure out how to solve or work around these problems. You
may also discover problems with the customization that require
software fixes.

<<What about copyrights, updates, guaranteed accuracy, etc.?>>

Retaining copyright is a simple matter of signing a contract (a
license) with the customer: "We grant you the right to change the
field names but we retain copyright of the resultin docs." That's
probably not legally necessary, but it can't hurt; I'm not a lawyer,
but it seems that the changes you mentioned would be minor
enough that a customer who tried to claim the modified docs as
their own would be infringing your original copyright. (Kinda like
obtaining a copy of "The Hobbit" and changing the name Bilbo to
Fred everywhere and claiming the book was your own.)

Updates and accuracy would be problematic because you'd
potentially have to provide and verify a different update for every
customer. If you have no control over the changes, you need some
means of informing your support staff of what field someone is
talking about, even if the name has been changed beyond
recognition. (For ex.: "I don't know what to enter in the field named
'Field 17G Customer name". Techie looks up field 17G in the
support database and continues solving the problem.) This would
require some kind of assistance from your developers to figure out
a painless way to implement the solution.

Turning this "problem" into an opportunity might be a very good
idea; in effect, you develop your own approach for customizing the
names without changing the rest of the documentation, then sell
this to customers for a nominal fee that recovers your costs. As a
result, you get income, you retain full control of the documents,
and you can provide the customization information to the tech
support staff so they know what customers have done to the
software or docs.

--Geoff Hart @8^{)} geoff-h -at- mtl -dot- feric -dot- ca (Pointe-Claire, Quebec)
"If you can't explain it to an 8-year-old, you don't understand it"--Albert Einstein

Previous by Author: Acrobat lists: summary
Next by Author: (Re)configurable?
Previous by Thread: Working in Brazil
Next by Thread: Preliminary results - Survey of writers in small and startup soft ware companies

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

Sponsored Ads

Sponsored Ads