The issue of customers wanting customised help crops up regularly and can be broadly split into two requirements:
- Customised Topics
- Customised Terms
Customised topics can mean both the ability to edit or add to the content and the ability to add comments as a footnote. The complexities that surround both explain why no help authoring tool offers this functionality despite the fact that it would be a marketing success. This page covers the complexities of customised topics rather than any solution. Two solutions are suggested at the end.
Customised terms are easier to deal with since RoboHelp 6 introduced User Defined Variables. These still need to be set up using RoboHelp but it can be done by the original author delivering the an output with the required variable values.
What is it the customer wants?
Typically customers want the help to guide their users through the processes they have implemented and here we hit the problem. Help topics that are process based will be written according to the standard process, which may not be how the customer has implemented it.
Customising for their particular needs may involve a considerable rewrite with the attendant costs. Charge out rates vary but using ball park figures these could be in the region of £250/500 per day and whilst the time will obviously vary with the level of change, it is not difficult to envisage five to ten days work.
Experience shows that in tender requests it is standard practice to request the ability to customise the help; the people who write these documents have to show they have covered all possible requirements. It is only later they realise they don't have the skills to edit the help (if the project can be made available to them) and nor do they want to pay for the work to be done. That's ignoring updates further down the line.
What is really needed is a means of adding to topics either at the required point or as a footnote but no authoring tool offers that.
What is involved in identifying the changes?
This could be done entirely by the customer to minimise their external costs. However they would probably require an initial overview of the help structure and maybe a version of the help in Word format. Depending on the content of the help, this could vary from just a few hours work to a several days.
More likely though is that they will want the work done for them, in whole or in part. Analysis may be required of the process(es) they follow and then analysis of what changes to the help are required as a result. This will be a joint effort. Even if the customer identifies all the changes, the impact on the help will require some analysis time. Potentially there are a lot of costs here.
Making the changes in the first instance.
It is important to understand the issues that arise in the actual creation of the customised help and the maintenance issues that will arise. Here we will look at the issues that surround creating the help.
What's involved here will depend on the tool with which the help was created.
The RoboHelp product provides the familiar help interface of a Toolbar allowing selection of a Contents Page, an Index and a Search function, plus the display of any selected topic. The newer HTML5 outputs allow the content to be viewed on any device be it a PC, a tablet or a smartphone. RoboHelp offers much more functionality to the author and end user than outputs created using other Word or suchlike.
Other HTML Editors
Help can also be written in pretty much any HTML editor. There will not be an index and navigation will be by dropdown menu or a list of options. The reason RoboHelp is preferred by technical authors is that it is significantly better in these areas, ignoring many other advantages.
- If the help is created with RoboHelp, it needs to be edited by someone proficient in its use. Sometimes customers will volunteer that they will buy a licence and do the editing. By definition that means they are not already using it and do not have someone skilled in its use. Expect lots of phone calls to your authors seeking help.
- The next suggestion is usually something like, "We'll give it to IT Support, they can learn how to use it."
First take into account that basic RoboHelp training will cost in the region of £1,000 and the trainee will certainly not be experienced and will not use the product regularly so their new skills will soon diminish.
Secondly why not give them Visual Basic and let them write the application as well? The point here is that RoboHelp is not just a simple word processing package and its users are typically called Technical Authors.
- In theory the output pages from RoboHelp can be edited in other HTML editors but it is not a path I would recommend other than for the most basic of changes such as amending the name of a hyperlink or its target.
- If the help is written using some other HTML editor, it will be easier for customers to make basic changes provided they have staff proficient in HTML. This sort of help though is not best suited to big applications.
The customer states they have the skills to make the changes.
The help that is provided with an application is the output, much like the application has an exe file. For the customer to be able to make the changes, they will need the source files for the help. Consideration needs to be given as to whether these are going to be released.
It will also be important to make it clear
- Whether support will be given to whoever is making the changes and on what basis.
- What happens if the help does not work in the application after the customer has made changes and whose responsibility it is.
The customer accepts they do not have the skills to make the changes, what can we do?
Subject to resource availability, the changes can be made for them. However, we are then back to the costs and where resource is not available, contract resource will be required, probably at an even higher cost, even ignoring the contractor will require additional time for familiarisation.
A process will need to be agreed as to who identifies the changes and how they are communicated to the person making them.
The revised help will be installed for the customer and responsibility accepted if it does not work for whatever reason.
The real fun bit is when the product upgrades are issued. The upgrade is installed on the customer's systems and the new help overwrites all their customised help. Boy do they love that one!
Fortunately it is easily resolved as long as they have kept their backups, the person who knows about RoboHelp or the HTML editor is still working there etc etc. None of those will be an issue will they? If you think not, perhaps I can also ask if you still believe in the tooth fairy? You need to consider this aspect when the initial request is being handled so that both sides can make sure it is not an issue further down the line.
The bigger consideration though is the work in updating the original customised help. The standard product help must be updated, obviously, but so must the customised help. What are the issues here.
- If the original customisation was limited to inserting additional help, then each change to the standard product help needs to be duplicated in the customised version, at the least. That may also necessitate further changes in the customised version, which returns us to who makes those and so on.
- If the help was restructured, then each change to the original help will need to be reviewed against the customised help.
Time now for a grenade. The customer is not going to upgrade for six months or so and wants the help upgraded then when they have a budget rather than now when the changes are fresh in your mind. Or better still, they are not going to upgrade now but decide to several versions further on. Now multiply what is going through your mind in terms of the logistics by each customer who has customised help. OK I am setting out the worst case but the point is it can become a resource nightmare with heavy attendant costs.
Is there no solution or compromise?
As I indicated at the outset, many requests for customised help arise from the need of the person writing the tender request to show that they have thought of everything. In fairness that is their job. The response needs to indicate willingness to meet the requirement but also to show the cost. In most instances this leads to the request disappearing completely but sometimes a lower cost compromise will be sought.
Links to Customer Files explains one solution both in general terms for explanation to customers and in technical terms for the author. The work involved did not prove popular!
If you find the information and tutorials on my site save you time figuring it out for yourself and help improve what you produce, please consider making a small donation.
Changes to this page
04 Feb 2017
Topic reviewed including removed reference to AIR Help as that output is no longer being developed.
11 Apr 2011
Update re AIR Help added.
19 May 2007
Reference to KnowHow added.
20 Mar 2005
Introduction amended to reflect development of RoboHelp.
09 Jan 2005