Help System

Old fishing hamlet of Helgumannen. Faro, Gotland. Sweden

Help System

part of the ArsDigita Community System by Philip Greenspun

User directory: /help/
User directory (complete system guide): /help/guide/
Admin directory: /admin/help/
Admin directory (complete system guide): /admin/help/guide/
Data model: none (file system-based)
procedures (includes ADP tags): /tcl/help-defs.tcl

The Big Idea

We want a standard way of documenting a site for end-users. We need

documentation for the whole site that gives a new user or administrator a high-level perspective of system capabilities
documentation of individual pages
documentation of words or phrases

We want to achieve the following technical objectives:

we only have to change documentation style (e.g., background color, font design) in one place
a single documentation file can be authored in such a way that users with different levels of privilege or service will see only the relevant portion
documentation authors can continue to use familiar tools, e.g., tools that are optimized for authoring HTML (perhaps with a few extra tags)

The Medium-sized Idea

The high level documentation is in traditionally authored directories of HTML files, but we augment HTML with a set of additional tags to enforce site-wide style conventions (these will be a superset of the site-wide style tags used by online pages, as described in /doc/style.html). The augmentation also provides for tags that will switch on a section only if a user has selected a particular feature (for example, in a documentation production site, only users whose companies have elected "fancy workflow authorization" will see sections related to that). Sometimes we augment HTML in order to provide greater convenience for the documentation authors, for example, we provide by default a glossterm tag that saves a doc author from having to hard-code in a link to the ACS glossary module: /glossary/one.tcl?term=film.

The page-level documentation is stored in conventionally named files underneath the Web server root. Support is provided for multi-lingual documentation.

The standard ACS /glossary module is used to provide word and phrase definitions.

Under the hood

We use ADP pages to create all documentation. This allows us to register special tags using ns_register_adptag. These special tags help enforce site-wide style conventions as well as providing a mechanism that will act as a switch for a particular section. For instance, the code run by the special tag may check whether or not the user is a member of a particular user group. If the user is in the group, then the procedure returns the string between the tags with the appropriate font and formating. If the user is not in the group, then the procedure returns the empty string.

We place a call to help_link on every page that could potentially have a help file. This procedure determines whether or not there actually is a help file associated with the given file. If a help file exists, help_link returns a string containing a link to a page that will serve the requested help file. If no help file exists then the empty string is returned.

We name all page-level help files with the same filename as the page that they document, with a .help extension. For instance, if we have a URL named foo.tcl, the help file will be named foo.help. If a multi-lingual help system is in place then the help file in english will be foo.en.help (the help file in french will be foo.fr.help, etc.). Language encoding and the sorting out of user preferences are as described in /doc/style.html.

These help files reside in a directory hierarchy mirroring that of the files that they document, rooted at a location specified by the HelpPageRoot parameter in the ns/server/servername/acs/help section of the server's auxiliary .ini file. This parameter specifies the root of the help file's directory hierarchy as a relative path from the server's page root, so HelpPageRoot=/help would specify that all help files lived under /web/servername/www/help. Leaving it blank specifies that the help page root is the same as the server's page root, so .help files reside in the same directories as their corresponding .tcl files.

.help files are registered to be interpreted as ADP files so that they can be viewed directly, in order to aid in their development.

If you really love our ideas...

If you really really love the photo.net/ACS style then you'll have kept the Yahoo-style context/navigation bars above the top HR in most of your scripts. It seems to us that a natural companion to this is a help link just underneath the HR and to the far right of the page. As long as we've got that, we might as well also include other options that are sort of outside the normal realm and flow of what a user might be doing with the page. For example, an "administer" link could go there.

To faciliate this style of programming, we've defined help_upper_right_menu which takes an arbitrary number of optional args, each of which is a list of URL and anchor (similar to the ad_context_bar args). These are extra options on the menu and they will be displayed in the order supplied, followed by a help link (if the .help file is found in the file system).

The Steps

decide whether you want to go multi-lingual or not.
decide what types of things you would like to standardize. Examples could be setting a specific, easily changable font or linking glossary terms to their definitions.
define a special tag for each type of item that should be standardized.
define a special tag for each type of content switch you would like to have (for instance, if you only want to show the workflow section to specific companies, you can wrap the workflow section in a <workflow> tag).
insert calls to help_link in your .tcl scripts and .adp templates

philg@mit.edu