Customizable docs?

["Geoff Hart" <geoff-h -at- mtl -dot- feric -dot- ca>]

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 
manual?"

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