This article describes a set of tools and techniques for developing on-line help for ASP.NET applications. It is intended for developers who are approaching the task of developing on-line help to accompany an ASP.NET application for the first time. It describes how to utilise web pages to provide on-line help. It describes the Microsoft tools of Visual Studio and Visual Web Developer. It does not cover the use of HTML Help Workshop which is unable to produce on-line help for use by ASP.NET applications. The consideration of various third party tools that perform similar tasks is beyond the scope of this article.

The article uses the example of the Ferrysoft Help Desk application and associated on-line help as illustration.

The tools used to develop the Ferrysoft Help Desk application are described in the following table.

Tool	Use
Visual Studio or Visual Web Developer	Authoring the topic files in HTML format that are used to create the final on-line help.
Visual Studio or Visual Web Developer	Establishing the connection between the web pages of an ASP.NET application and the on-line help.

Help files are organised into help topics. The choice of help topics is a design decision that determines how sophisticated the eventual on-line help will be. Probably the simplest structure of help topics is to have one help topic per web page. More sophisticated on-line help could be designed with different topics for each element of a web page. Alternatively, help topics could describe the general features of the application without being bound to a particular web page.

In the Ferrysoft Help Desk case, there is one help topic for each of the web pages within the application. Each web page has a Help hyperlink so that help can be obtained by clicking the Help hyperlink.

Each help topic is authored as a single HTML file. The naming convention for the topic files follows the naming convention of the corresponding web pages for convenience. For example, default.htm contains the help text that describes the home page, contained in default.aspx within the application. All of the topic files are located in a sub-folder of the application folder named help so that they can be referenced by a relative path, for example, help/default.htm.

Hyperlinks can be inserted in the help topic files and these become hyperlinks that can be clicked when using on-line help. This provides a convenient way to navigate between help topics. Below is an example of a hyperlink that could be included to link to the home page help topic contained in default.htm.

<a href="default.htm">Home Page Help</a>

Unlike help files built with HTML Help Workshop, this approach does not automatically provide for a Table of Contents. Some developers take the approach of using a frames web page so that a Table of Contents can be shown in a frame on the left-hand side of the page and the help topic can be shown on the right-hand side of the page. This has the benefit that the Table of Contents can be authored once but has the disadvantage that a frames web page is used which has some intrinsic drawbacks. Ferrysoft Help Desk doesn't use a frames web page but instead provides a Table of Contents in each topic file which avoids the frames web page drawbacks. The Table of Contents is contained in the left-hand cell of a two cell table with the help topic contained in the right-hand cell. This creates a visual appearance that is similar to a frames web page solution.

The on-line help for Ferrysoft Help Desk uses a common Cascading Style Sheet (CSS) for every help topic. One benefit of this is that the colour of the hyperlinks within the on-line help can be explicitly controlled so that visited and unvisited links have the same colour. This provides a more pleasing visual effect as the user navigates within the on-line help topics.

Visual Studio and Visual Web Developer are suitable tools for developing the help topic files. Other tools for authoring HTML files could be used instead. Even a text file editor such as Notepad could be used to prepare the help topic files although this would make it more difficult to get the HTML syntax correct.

The image below shows Visual Studio with the help files folder open and the default.htm help topic file open in design view.

Below is the Ferrysoft Help Desk default.htm as an example of a complete help topic.

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
    <head>
        <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
        <title>Ferrysoft Help Desk Help - Home</title>
        <link rel="stylesheet" type="text/css" href="ferrysofthelpdeskhelp.css" />
        <meta name="robots" content="noindex" />
    </head>
    <body>
        <div class="header">
            <div class="headerleft">Help</div>
            <div class="headerright">Home</div>
            <div class="formclear"></div>
        </div>
        <div class="menubar">
            <div class="menubarleft"></div>
            <div class="menubarright">
                <a href="http://www.ferrysoft.co.uk">
                Ferrysoft Home</a>
                <a href="http://www.ferrysoft.co.uk/support.htm">
                Ferrysoft Support</a>
            </div>
            <div class="formclear"></div>
        </div>
        <table class="maintable">
            <tr>
                <td class="bodyleft">
                    <p class="menu1">Help Desk</p>
                    <div class="menulist">
                        <p><a href="default.htm">
                        Main</a></p>
                        <p><a href="newcase.htm">
                        New Case</a></p>
                        <p><a href="reports.htm">
                        Reports</a></p>
                        <p><a href="myprofile.htm">
                        My Profile</a></p>
                        <p><a href="administration.htm">
                        Administration</a></p>
                    </div>
                    <p class="menu1">Discussion Forum</p>
                    <div class="menulist">
                        <p><a href="discussionforum.htm">
                        Discussion Forum</a></p>
                        <p><a href="discussionshowtopic.htm">
                        Show Topic</a></p>
                        <p><a href="discussionnewtopic.htm">
                        New Topic</a></p>
                        <p><a href="discussionpostreply.htm">
                        Post Reply</a></p>
                        <p><a href="discussionsendemail.htm">
                        Send Email</a></p>
                    </div>
                    <p class="menu1">Knowledge Base</p>
                    <div class="menulist">
                        <p><a href="knowledgebase.htm">
                        Knowledge Base</a></p>
                        <p><a href="knowledgeshowtopic.htm">
                        Show Topic</a></p>
                    </div>
                    <p class="menu1">Administration</p>
                    <div class="menulist">
                        <p><a href="announcements.htm">
                        Announcements</a></p>
                        <p><a href="discussions.htm">
                        Discussions</a></p>
                        <p><a href="contacts.htm">
                        Internal Contacts</a></p>
                        <p><a href="knowledgebases.htm">
                        Knowledge Bases</a></p>
                        <p><a href="lists.htm">
                        Lists</a></p>
                        <p><a href="organisations.htm">
                        Organisations</a></p>
                        <p><a href="priorities.htm">
                        Priorities</a></p>
                        <p><a href="setupexternalinterfaces.htm">
                        Setup External Interfaces</a></p>
                        <p><a href="setupregistrationkey.htm">
                        Setup Registration Key</a></p>
                        <p><a href="setupsystemdefaults.htm">
                        Setup System Defaults</a></p>
                        <p><a href="users.htm">
                        Users</a></p>
                    </div>
                </td>
                <td class="bodyright">
                    <p>Use this page to list a selection
                    of cases or to access other pages for
                    other features of Ferrysoft Help Desk.
                    The availability of options and features
                    described here will depend on the type of
                    user and the roles assigned to that user.
                    If an option or feature is not available
                    then it may not be displayed on the page
                    or it may be displayed but in a disabled
                    state.
                    The pages available from this page are:</p>
                    <table class="topic-table">
                    <tr>
                        <td class="topic-table-top">
                            Option
                        </td>
                        <td class="topic-table-top">
                            Description
                        </td>
                    </tr>
                    <tr>
                        <td class="topic-table-hyperlink">
                            <a href="newcase.htm">
                            New Case</a>
                        </td>
                        <td class="topic-table-cell">
                            Use this page to enter the details
                            of a new case.
                        </td>
                    </tr>
                    <tr>
                        <td class="topic-table-hyperlink">
                            <a href="myprofile.htm">
                            My Profile</a>
                        </td>
                        <td class="topic-table-cell">
                            Use this page to modify details
                            of the current logged in user.
                        </td>
                    </tr>
                    <tr>
                        <td class="topic-table-hyperlink">
                            <a href="reports.htm">
                            Reports</a>
                        </td>
                        <td class="topic-table-cell">
                            Use this page to generate current
                            or periodic reports of cases.
                        </td>
                    </tr>
                    <tr>
                        <td class="topic-table-hyperlink">
                            <a href="administration.htm">
                            Administration</a>
                        </td>
                        <td class="topic-table-cell">
                            Use this page to access further
                            administration pages.
                            This option is only available to
                            users who are internal contacts
                            with the Administrator role.
                        </td>
                    </tr>
                    <tr>
                        <td class="topic-table-hyperlink">
                            <a href="existingcase.htm">
                            Go&gt;&gt;</a>
                        </td>
                        <td class="topic-table-cell">
                            Use the Go button to retrieve the
                            case using the Case ID entered in
                            the Case box and display it in the
                            Existing Case page.
                            The Existing Case page can then be
                            used to save changes to the case or
                            delete the case.
                        </td>
                    </tr>
                    </table>
                    <h3>Status</h3>
                    <p>Status allows the display of cases
                    to be filtered.
                    The default status filter is
                    &quot;Open&quot;.</p>
                    <h3>Priority</h3>
                    <p>Priority allows the display of cases
                    to be filtered.
                    The default priority filter is
                    &quot;&lt;Any&gt;&quot;.</p>
                    <h3>Assigned To</h3>
                    <p>Assigned To allows the display
                    of cases to be filtered.
                    The default assigned to filter is the
                    name of the current user if the current
                    user is an internal contact.
                    Otherwise the default assigned to filter is
                    &quot;&lt;Any&gt;&quot;.</p>
                    <h3>Customer</h3>
                    <p>Customer allows the display of
                    cases to be filtered.
                    The default customer filter is
                    &quot;&lt;Any&gt;&quot;.</p>
                    <h3>Contact</h3>
                    <p>Contact (customer) allows the
                    display of cases to be filtered.
                    The default contact filter is the name
                    of the current user if the current
                    user is a customer contact.
                    Otherwise the default contact filter is
                    &quot;&lt;Any&gt;&quot;.</p>
                    <h3>Supplier</h3>
                    <p>Supplier allows the display of
                    cases to be filtered.
                    The default supplier filter is
                    &quot;&lt;Any&gt;&quot;.</p>
                    <h3>Contact</h3>
                    <p>Contact (supplier) allows the
                    display of cases to be filtered.
                    The default contact filter is the name
                    of the current user if the
                    current user is a supplier contact.
                    Otherwise the default contact filter is
                    &quot;&lt;Any&gt;&quot;.</p>
                    <h3>Refresh button</h3>
                    <p>Use the Refresh button to
                    refresh the list of cases according to
                    the selected filters.</p>
                    <h3>Cases list</h3>
                    <p>The Cases list shows the cases
                    matching the filter criteria.
                    Clicking a column heading sorts the list
                    according to the entries in the column.
                    Subsequent clicking of the column heading
                    toggles the sort order between ascending
                    and descending.
                    Click the Modify link to access the
                    <a href="existingcase.htm">
                    Existing Case</a> page for the
                    selected case.</p>
                </td>
            </tr>
        </table>
        <div class="footer">
            Powered by <a href="http://www.ferrysoft.co.uk">Ferrysoft Help Desk</a>
        </div>
    </body>
</html>

The image below shows Visual Studio with the help files folder open and the CSS file open for editing.

Below is the CSS file (ferrysofthelpdeskhelp.css) for the Ferrysoft Help Desk on-line help.

a:link{
    color: blue;
}
a:visited{
    color: blue;
}
body{
    margin: 0px;
    padding: 0px;
    font-family: verdana,arial,helvetica,sans-serif;
    font-size: small;
}
table{
    border-style: none;
    border-width: 0px;
    border-collapse: collapse;
}
td{
    vertical-align: top;
}
.bodyleft{
    background-color: #F0F0F0;
    width: 200px;
    padding: 0px;
}
.bodyright{
    font-family: calibri,verdana,arial,helvetica,sans-serif;
    font-size: medium;
    border-top-style: solid;
    border-top-width: 1px;
    border-top-color: #C0C0C0;
    border-left-style: solid;
    border-left-width: 1px;
    border-left-color: #C0C0C0;
    padding-top: 16px;
    padding-right: 16px;
    padding-bottom: 16px;
    padding-left: 16px;
}
.footer{
    background-color: #7FBFFF;
    font-size: x-small;
    width: 100%;
    margin: 0px;
    padding-top: 8px;
    padding-right: 0px;
    padding-bottom: 8px;
    padding-left: 0px;
    text-align: center;
}
.footer a:link{
    color: black;
}
.footer a:visited{
    color: black;
}
.formclear{
    clear: both;
}
.header{
    background-color: #7FBFFF;
    width: 100%;
}
.headerleft{
    width: 200px;
    margin: 0px;
    padding-top: 4px;
    padding-right: 0px;
    padding-bottom: 4px;
    padding-left: 8px;
    float: left;
    font-size: x-large;
    font-weight: bold;
}
.headerright{
    margin: 0px;
    padding-top: 4px;
    padding-right: 0px;
    padding-bottom: 4px;
    padding-left: 0px;
    font-size: x-large;
    white-space: nowrap;
}
.maintable{
}
.menu1{
    font-weight: bold;
    margin-top: 0px;
    margin-right: 4px;
    margin-bottom: 0px;
    margin-left: 4px;
    padding-top: 2px;
    padding-right: 8px;
    padding-bottom: 3px;
    padding-left: 8px;
    color: white;
    background-color: #C0C0C0;
}
.menubar{
    background-color: #F0F0F0;
    width: 100%;
}
.menubarleft{
    width: 200px;
    padding-top: 4px;
    padding-right: 0px;
    padding-bottom: 4px;
    padding-left: 8px;
    float: left;
}
.menubarright{
    padding-top: 4px;
    padding-right: 0px;
    padding-bottom: 4px;
    padding-left: 0px;
    white-space: nowrap;
}
.menubarright a:link{
    margin: 0px;
    padding-top: 0px;
    padding-right: 8px;
    padding-bottom: 0px;
    padding-left: 8px;
    text-decoration: none;
    border-style: solid;
    border-width: 1px;
    border-color: #F0F0F0;
}
.menubarright a:visited{
    margin: 0px;
    padding-top: 0px;
    padding-right: 8px;
    padding-bottom: 0px;
    padding-left: 8px;
    text-decoration: none;
    border-style: solid;
    border-width: 1px;
    border-color: #F0F0F0;
}
.menubarright a:hover{
    background-color: #E0E0E0;
    text-decoration: none;
    border-style: solid;
    border-width: 1px;
    border-color: #C0C0C0;
}
.menulist{
    background-color: #F0F0F0;
    width: 200px;
    padding-top: 0px;
    padding-right: 0px;
    padding-bottom: 0px;
    padding-left: 0px;
}
.menulist a:link{
    margin-top: 0px;
    margin-right: 4px;
    margin-bottom: 0px;
    margin-left: 4px;
    padding-top: 0px;
    padding-right: 4px;
    padding-bottom: 0px;
    padding-left: 4px;
    text-decoration: none;
    border-style: solid;
    border-width: 1px;
    border-color: #F0F0F0;
}
.menulist a:visited{
    margin-top: 0px;
    margin-right: 4px;
    margin-bottom: 0px;
    margin-left: 4px;
    padding-top: 0px;
    padding-right: 4px;
    padding-bottom: 0px;
    padding-left: 4px;
    text-decoration: none;
    border-style: solid;
    border-width: 1px;
    border-color: #F0F0F0;
}
.menulist a:hover{
    background-color: #E0E0E0;
    text-decoration: none;
    border-style: solid;
    border-width: 1px;
    border-color: #C0C0C0;
}
.menulist p{
    margin-top: 4px;
    margin-right: 0px;
    margin-bottom: 4px;
    margin-left: 0px;
}
.topic-table{
    background-color: #F0F0F0;
    border-style: solid;
    border-width: 2px;
    border-color: #7FBFFF;
}
.topic-table-cell{
    font-weight: normal;
    color: black;
    border-style: solid;
    border-width: 1px;
    border-color: #7FBFFF;
    padding: 4px;
}
.topic-table-hyperlink{
    font-weight: normal;
    color: black;
    border-style: solid;
    border-width: 1px;
    border-color: #7FBFFF;
    padding: 4px;
    white-space: nowrap;
}
.topic-table-top{
    border-style: solid;
    border-width: 1px;
    border-color: #7FBFFF;
    background-color: #7FBFFF;
    padding: 4px;
}

The final stage is to establish the connection between pages of an ASP.NET application with the individual help topics. This is done with Visual Studio or Visual Web Developer to set the appropriate properties of a Help hyperlink to refer to the corresponding help topic.

In the case of Ferrysoft Help Desk, the Help hyperlink is defined in a master page file which is common to several web forms, including default.aspx. This allows most of the Help hyperlink properties to be set in one place and only the NavigateUrl property needs to be set individually for each web form, at run time. If, instead, the Help hyperlink was defined in each web form then all of the properties, including NavigateUrl, could be set at web form design time.

The image below shows Visual Studio with the default master web form open.

A HyperLink component is used to associate a help topic file with the web form. Therefore a HyperLink needs to be added to each web form as follows:

1. Open the web form in Design View.
2. Drag a HyperLink control from the Standard Toolbox to the web form.
3. Set the properties of the HyperLink in the properties window, for example, Text to Help, Target to _blank and NavigateUrl to help/default.htm. Note that setting Target to _blank will cause the on-line help topic to open in a new browser window when the Help hyperlink is clicked.

The image below shows the Ferrysoft Help Desk Home page.

If the user clicks the Help hyperlink then the on-line help topic is displayed to the user.

The image below shows the Ferrysoft Help Desk Help Home page.

Using Visual Studio or Visual Web Developer, it is possible to quickly develop on-line help that will enhance the usability of an ASP.NET application.

Mike Green is the founder of Ferrysoft, a software development company specialising in Help Desk software technology.