Integrated Help System
by Kenneth Richards - Monday, November 24, 2003
from the Development dept.

Currently, I am in the process of writing an integrated help system which will provide instructions for the administration areas of ASP Nuke. This will serve as a help reference and tutorial for people who are new to the Content Management System.

After writing some code to place the documentation in the database, I am wondering if it would be better to keep these as static web pages. The benefits of doing this would be that authors of modules could provide documentation in their packages as a normal web page.

With the content in the database, we would have to develop data import files which are parsed by an ASP application and placed in the database. The benefit of having the help documentation in the database is that it would be searchable (if necessary) and the administrator would be able to edit the help documents and add notes where necessary.

What I propose to do is to create a hybrid system where the help is located in static HTML files (.asp actually) that will hold some meta-information that allows the help document to be read and parsed by an ASP application and placed in the database.

While we could use XML to store the help documentation, I prefer HTML because it is more widely understood and it allows us to easily integrate markup codes in the content for inclusion in the reference material.

One issue that will arise using this method, is that the first time the help documentation is imported into the database, the application will ONLY read help documentation from the database. That means if an uneducated administrator goes and edits a help doc (as a web page,) the changes will not appear in the integrated help.

There will be administration tool to reload a help page from the web site. But unless the administrator knows about this, it could get very confusing. Well, forgive me for thinking this through on this article. It was the best way of moving forward with this project.