Modules for Sale

This site shows you how to set up several features for your web-based documentation, from collecting data from forms, to sending email from within your documentation, to creating a tag library to provide your site with conditionalization features to include or exclude content based on the user.

Some modules are more complicated, though, and require more Java programming. I have started development of several modules that you may find would enhance your web-based documentation. These modules will be available for purchase, and come with documentation that:

• can be downloaded before you purchase the module

• shows you how to install the modules on your web server

• shows you how to incorporate the module functionality within your web site

• includes code samples

• includes live examples on my web site

You've been meaning to go through and create a glossary for your documentation for some time, but never seem to have quite enough time to get the job done. It's one thing to find words that should be in the glossary and create the explanation of the terms, but it is entirely another to go through all of the documentation looking for occurrences of the words, and link them to the glossary. And then, you'd want to make sure you had created an exhaustive glossary before starting, so that you wouldn't have to go through the search-and-link process more than once.

If you buy the glossary module I have created, you still have to determine what words to create glossary entries for, and you have to create the glossary definitions, but the rest of it is handled for you automatically. You merely install the module on your web server, and then you run a utility that inserts a line of code into all of your JSP and/or HTML pages. You find the words you want to define, and create HTML pages to define them. Then, you update a configuration file (the equivalent of a Windows .ini file or the Windows 9x Registry) to include the word and a the URL for the definition.

The module will then automatically link the first occurrence of each glossary term in each topic. When your users click the link, a popup window appears, with the definition you have created. You can determine the size of the popup window. You can make the glossary module case-sensitive or case-insensitive on a case-by-case basis. This way, if you have a certain commonly-used word that has a special meaning only when the first letter is capitalized, you can have the module only link the term when first-letter-capitalized instances of the word appear in the documentation.

But the best part is, you can add words to your glossary as you have time for them, and they will automatically be linked on your site. No more need to modify the documentation source files once you have run the utility that adds a single line of code to each file. As you add new HTML pages to your documentation, you can add that line of code to those pages, too, and they will automatically have their glossary terms linked.

Would you like to know how your users use your documentation?

The User Navigation Tracking module lets you determine when users follow the browse sequence for your site, when they follow See Also links at the bottom of the page, and when they go to the Table of contents, index, or full-text search to continue in their search for the next topic. It also stores the amount of time that users remain on the topic before moving to the next one.

You can use this information to:

• add “See Also” references to your topics

• change the browse sequence of your site

• add a feature that shows users what topics other users moved to from the current topic

• determine the average length of time users spend on a given topic

The information is stored in a way that allows you to both:

• review collective information on a particular topic (such as the average amount of time spent on the topic, and what topics were commonly visited before and after the topic), and

• track an individual series of navigations (such as what topics were visited in what order, how long the user stopped at each topic, and what topic was at the end of the user's search)

The module has two versions. The first lets you store the data collected on your own web server, and provides a database schema so that you can set up the required database tables. The second version stores the data on my web server.

Both versions provide reporting pages that present data to you in a set of easily-to-read tables. Following are two examples of tables produced by the reporting pages. Note that the tables are representative of how the tables appear at the time of the writing. I will try to keep this page updated, but it is possible that the tables have been modified from this format in the actual module.

Topic-based report

The links in the Last 10 access dates/times row would link to a sequence-based report that follows that particular user's sequence through the documentation. The more link in that column would allow you to view earlier accesses of the topic.

You can modify the span of time shown in the Total number of accesses since, Previous page and Following page rows by entering a new date in the text box and clicking the New date button.

The Feedback row would only be accessible if you also purchase and install the User Feedback module. The link in that row would generate a report that presents the data that your users entered about that particular topic.

Sequence-based report

A sequence-based report will include a number of double-tables like the following. You will be able to specify the number of sequences to display, either by explicit number (show me the last 10), or by date (show me all sequences in the 7 days).

The Date/time of sequence row shows you the time that the sequence began. The Number of topics in sequence row indicates how many topics were visited before the session timed out. The Total time in sequence indicates the amount of time that the user spent in all of the topics except the last one (which it is not possible to track).

The second table shows you the topics that the user visited, in order. The Topic1 column shows you the first topic that the user started with. The n-5 column shows you the fifth-from-last topic, the n-4 column shows the fourth-from-last topic, and so on. In this example, the user only visited four pages before the session timed out, so there is only data in the Topic1, n-2, n-1, and n columns. If the sequence included more than seven topics, there would be some data omitted between Topic1 and n-5.

The first value in each cell in the second table is the name of the topic. The second value is the amount of time spent in the topic. It is not possible to track how long the user spent in the final topic (column n).

This module allows you to collect feedback on your documentation from your users, as they are using it. It inserts a form that you design at the end of each topic. You can make as many or as few of the fields mandatory as you want (I recommend making as few fields mandatory as possible...you probably don't want to cause your users to change their minds about providing feedback).

The module provides a set of reporting pages that allow you to review the data entered in a date-based or topic-based order.

This module comes with a Java utility that will parse your JSP files and insert the necessary code into the pages to automatically add the form to the bottom of the page.

Often, when a user is working on a particular part of the product you are documenting, they will visit the same few reference topics regularly. This module allows you to put links to these topics on a home page for them, similar to a portal page feature. The information about what topics the user has visited recently, or has selected as favorite topics, can be compiled based on the user's primary IP address, or by having the users log in to the documentation. The former is better when it is a viable option, but the latter option allows you to provide the feature to those who have a dynamic IP address, or who move between different computers. You can allow your users to bypass the login screen if they do not want to take advantage of the feature, of course.

This particular model isn't quite as self-running as the other modules. It is actually packaged as a JavaBean. This requires that you add a bit of code to the page that you list the recently used/favorite topics on, but it also gives you flexibility: you can enter as many or as few as you want (or as they specify), you can mix recent topics and favorite topics, or have two separate sections, and so on. The documentation provides ample support for the different ways that you can use the Bean in your documentation web site.

Imagine enabling your users to view every single topic that has changed since the last release...and even color-coding the changes for them!

Using this module, you put in a tag each time you make a change to your documentation for the next release. (It sounds time-consuming, but it actually is an easily-developed habit.) The tag that you put in will look something like this:

<ver:Version num="2.1.1">Content new or changed in version 2.1.1 goes here</ver:Version>

After you tag content for the version, you can create a list of topics that have been added or changed in a given release. In fact, you can provide a list of topics changed/added from any release to any release. So, if you're releasing version 4.2, and some of your users are back on version 2.0, you can provide a list of the topics that were changed or added for all of the releases in between.

But, it gets better. Not only will your users have all of the new and improved topics pointed out to them, but they will have the option of color-coding the content, so that they can see the exact text that changed. They can turn the color-coding on or off as needed, so that it doesn't become distracting.

Have some text that was added in version 2.0, was still valid in 2.1, but describes functionality that was replaced in version 3.0? A simple modification of the standard tag makes it so that your users only see what is appropriate for their release.

Here's how that tag would look:

<ver:Version num="2.0" endNum="2.1">Content for 2.0 and 2.1 versions, but not for 3.0 and later goes here</ver:Version>

Now, your users indicate that they are using version 3.0, and they want to have material color-coded for them. The new 3.0 material will display in whatever color they choose, but the 2.0 and 2.1 functionality is not shown. This can greatly simplify things for your users.

This module comes with a utility that will scan the contents of your documentation for instances of the tag. The information that the utility compiles is used to generate lists of topics that have changed from one release to another. Users don't even have to visit the particular topics to view the new material (which is especially helpful if you long topics). The utility also generates a JSP topic that links the references to the page to a pop-up that displays the added or changed material.

Here is an example of the generated output:

...

Using your dehydrator to dry worms and insects for bait

Dehydrator recipes

Cleaning and care of your dehydrator

...

Have an idea for a module?

Do you have an idea for a module that you would like to see created? Please explain in as much detail as you can the functionality that you would like to be able to integrate into your web-based documentation. I will contact you about whether the module seems feasible, and whether I think it would be of widespread-enough value to create and make available to the public. If it is not likely to be of widespread value, I can provide you with an estimate of the cost to generate the module for your company.

The fields with an asterisk (*) are required.