Online Help Design Deliverable Template
From MIKE2.0 Methodology
-> You are here: Online Help Design Deliverable Template
Throughout the project there will be training and support requirements, the creation of the Online Help Design task is specifically designed for the environment that is accessed by a business user. If a customized Business Intelligence application is to be developed any help systems or tutorials should be outlined in this task.
Online help and tutorials, which can be of significant help in assisting end-users, are frequently cited by users as a source of dissatisfaction. There are a number of process problems which lead to poor quality help. These include failing to allocate enough time and resources, having help screens produced by user interface developers who don’t understand what is needed, and robbing time from the production of help to make up for cost overruns and schedule slippages. Help is often treated as an afterthought activity, to be performed by developers at the end of the project.
There are several ways to improve the process of creating a help and tutorial system:
Example 1 - Approach to Online Help Documentation
Purpose of this Document
The purpose of this document is to recommend an approach to the issues currently outstanding in relation to the creation and maintenance of the XYZ Online Help.
ABC has developed and will deliver a generic online help project to XYZ as part of the CLIENT project. XYZ must then decide on and implement the best approach for the addition and maintenance of topics specific to their work practices. These topics must fit into the structure of the online help as seamlessly as possible so as not to discourage the business users from confidently searching for answers rather than asking their work neighbor. Keeping this in mind, it is also imperative that online help can be easily maintained.
Another issue, which has arisen, is the identification of the generic topics that will be created and maintained by ABC and the XYZ specific topics, which will be created and maintained by XYZ.
There is currently a list of outstanding issues that has been compiled from an audit of the online help by XYZ staff, which need to be dealt with by ABC prior to acceptance of the generic ABC project. These fall within the two categories of Content Error and Missing Topics. ABC will review the Content Errors this week.
Suggested Structure for the Online Help
How Can this Be Delivered?
Option 1 – Manually entering HTML into AAA compiled output
How will this be achieved?
This will be done by the technical writer entering the relevant HTML code into the appropriate html page. This could be done directly from the project output, or by selecting the page from the directory folder. The difficulty in selecting the page from the folder is that each page is numbered in such a way that the topic is not obvious.
In order to make this happen, the technical writer needs to be able to read and write HTML code as well as having a good understanding of HDK in order to create the initial XYZ project. The major requirement however is still a good knowledge of HDK as there may be some delivery issues relating to the XYZ Project that need to be identified and overcome.
The linking process from one project to another has a few quirks when compiling help projects in HDK using the JAVA TOC. This is not a big issue, however the user cannot return to the previous topic without pressing <Back> approximately 3 times.
The search (find) facility within the Help Project will only work within the currently opened project. Therefore, if you wish to search for a business procedure using the find option, you will need to ensure that you are in the XYZ Project and not the AAA Project.
Ongoing Maintenance Requirements
The maintenance tasks are quite onerous, as XYZ will be responsible for inserting and maintaining the hyperlinks in each project. The amount of work is dependent upon the number of links used in each project.
To create and maintain this project XYZ will require a technical writing resource familiar with HTML and HDK. However, once the technique on how to insert links using HTML has been accomplished, the majority of their time will be spent updating the XYZ project using HDK. This resource need not be full time however the task must commence as soon as possible to ensure that all materials are complete and that any technical issues, which may arise are ironed out well before training commences. Once the system is implemented this resource must be available for timely updates, which will occur as a result of ABC software releases or XYZ procedural changes.
Issues that may occur
Although this approach is not difficult in relation to the HDK product, it may prove to be ’painful’ in the early stages if frequent system changes occur.
Due to the complex nature of the AAA project, it is imperative that ABC provides adequate training and documentation to the XYZ technical writer, as there are some quirks in the way in which the project is coiled that may need to be emulated in the XYZ project. These quirks occurred as a result of the requirement by XYZ for the project to be delivered efficiently over a WAN (?).
User has advised that if the AAA online help is changed in any way that we will negate our support for this component of the system. This will also need to be considered prior to entering any links.
ABC would enter a generic tips link into each project topic in the AAA Project. The URL address for each link would be named appropriately so that XYZ could use the same naming convention for the corresponding XYZ Project topic.
This approach would eliminate the need for XYZ to change the AAA output and would therefore not negate the contract.
Ongoing Maintenance Requirements
Ongoing maintenance would be of the XYZ Project only. Care would need to be taken in naming the XYZ output to ensure that it ties in with the AAA links.
Issues that may occur
Due to the complex nature of the AAA project, it is imperative that ABC provides adequate training and documentation to the XYZ technical writer, as there are some quirks in the way in which the project is coiled that may need to be emulated in the XYZ project. These quirks occurred as a result of the requirement by XYZ for the project to be delivered efficiently over a WAN.
Wiki asset search