Open Framework, Information Management Strategy & Collaborative Governance | Data & Social Methodology - MIKE2.0 Methodology
Wiki Home
Collapse Expand Close

Collapse Expand Close

To join, please contact us.

Improve MIKE 2.0
Collapse Expand Close
Need somewhere to start? How about the most wanted pages; or the pages we know need more work; or even the stub that somebody else has started, but hasn't been able to finish. Or create a ticket for any issues you have found.

Online Help Design Deliverable Template

From MIKE2.0 Methodology

Jump to: navigation, search
Under construction.png
This article is currently Under Construction. It is undergoing major changes as it is in the early stages of development. Users should help contribute to this article to get it to the point where is ready for a Peer Review.
This deliverable template is used to describe a sample of the MIKE2.0 Methodology (typically at a task level). More templates are now being added to MIKE2.0 as this has been a frequently requested aspect of the methodology. Contributors are strongly encouraged to assist in this effort.
Deliverable templates are illustrative as opposed to fully representative. Please help add examples to this template that are representative of the proposed output.

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:

  • Plan for it, and allocate enough time and resources
  • Build the help system into the iterative release schedule, so that the system is available with early incremental releases, and feedback will be applied to the problem
  • Get trained people to do it
  • Use modern technologies, such as wikis, that allow for more dynamic documentation



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?

  • The ABC online help will be delivered as a compiled HTML project consisting of a master and several slave projects. When these are compiled they appear to the user as a single project, which share the same Table of Contents.
  • A single XYZ project will be created using HDK and will contain several procedure documents, which when compiled will share a common Table of Contents.
  • Within each of these projects will be hyperlinks that can be instigated from within either the XYZ project or the ABC project. There will also be hyperlinks between the procedure documents within the XYZ project.
  • Both the ABC and XYZ projects will share a common format, and therefore eliminate the need for the user to reacquaint themselves with a new look and feel each time they move from the ABC project to the XYZ project via the hyperlinks.
  • The XYZ project will contain several procedural flowcharts that can be converted into Segmented Hypergraphics, which will enable the user to click on a step of interest within the chart and be taken to a separate topic. Each topic within the process will also contain links to the following steps. This will enable the user to either access the process steps from the Table of Contents or from the flowcharts. Steps within the flowcharts that relate to system tasks will contain links to the ABC project, which will eliminate duplication of information.

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.

Option 2 – AAA Online Help to contain a Generic Tips link in each topic.

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 Contributors
Collapse Expand Close