Customising Help

 

 

What's covered?

This page describes what needs to be considered when customers request customised help topics. It is aimed at both technical authors and consultants / management dealing with the customer.

Providing links to customer produced files and intranets is a common request. Links to Customer Files / Intranets explains a process that was developed by the developers where I worked. It gave the customers what they had asked for but the setup and maintenance made them rethink their request.

RoboHelp 6 introduced User Defined Variables. These are a much easier way of creating multiple outputs where one uses the term Store, another uses Warehouse and another uses Depot.

Introduction

The issue of customers wanting customised help crops up regularly and can be broadly split into two requirements:

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.

RoboHelp

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.

Considerations

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.

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

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.

Product Upgrades.

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.

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!

Donations

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.

Topic Revisions

Date

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

New topic