JavaServer Pages for Technical Writers: Making Your Documentation Do More

JavaServer Pages (JSP) might be the answer to the age-old question, “How can I create documentation that is easy to maintain, that lets my users make changes that won’t be overwritten, that is customized for each individual user, that doesn’t require that I create more than one version of the document, and that doesn’t require plug-ins?”

By DAVID CASTRO
Unaffiliated

What is JSP?

JavaServer Pages (JSP) is a relatively new technology introduced by Sun Microsystems, Inc. Similar to Microsoft Active Server Pages from Microsoft, you can use JSP to create dynamic HTML pages. This type of dynamic HTML is not the same thing as “Dynamic HTML” (DHTML). For JSP, it refers to the ability to customize individual pages by incorporating information from other sources, such as the following:

• Other pages
  
  
• Database queries
  
  
• User input
  
  
• Software calculations

Who Can Use JSP?

JSP is most effective when you host a copy of your HTML- or XML-based documentation on your Web site. This gives you the greatest flexibility to interact with databases, e-mail servers, external applications, and so on.

If you create HTML- or XML-based documentation using an HTML editor (that is, you don’t use a program to generate HTML from another source), but cannot host your documentation on a Web server, you can still use some of JSP’s capabilities. See “Using JSP Without Hosting on a Web Server” to learn more on this subject.

Do You Have to Know Java?

The answers to this question are “no,” “yes, a little,” and “yes, a lot.”

If you have no experience with Java, it is possible for you to use JSP to enhance your documentation: you can use JSP tag libraries. JSP tag libraries are discussed in “Using Tag Libraries.”

If you know a little bit of Java, you can add scriptlets to your HTML topics. You can use scriptlets to embed Java functionality into your Web pages to enable them to do the following:

• Query a database
  
  
• Send an e-mail
  
  
• Collect data from a form
  
  
• Copy the content of another file into the current file (called server-side includes)

For additional information about scriptlets, see “Using Scriptlets.”

If you know enough to create Java programs, you can create your own JSP tag libraries. Other members of your documentation department can use the tag libraries to enhance documentation. They do not need to know Java to use JSP tag libraries; you only need to know Java to write them. Some ideas for JSP tag libraries are discussed in “More Ideas for JSP Tag Libraries”

Using Tag Libraries

If you do not know any Java, you can still add JSP functionality to your HTML- or XML-based documentation.

Example: Customizing online help for end-user needs

Let's consider a software application that interacts with three types of databases: Oracle, SQL Server, and MySQL. You want to customize the help topic depending on which database(s) the end-user is using.

1. Create a tag library that hides or displays content based on the database(s) that your end-user is using. To do this, you can use the wizard that is available on my Web site (jsp.davidcastro.com/tagbuilder.jsp).

2. Select a page that has content applicable to only one database. Link this page to the tag library by adding the following two lines of code at the beginning of the file:

   <%@ include file="checkLogin.jsp" %>

   <%@ taglib uri="web-inf/tlds/taglibrary.tld" prefix="cond" %>

   The first line includes some content that checks to see if the end-users have provided information about what database(s) they use. If they have not, this content redirects the end-users to a page that allows them to provide that information. Once they have provided the information, the content redirects the end-users back to this page, which can then conditionalize the content based on the information they provided.

   The second line provides information to the page about the tag library that conditionalizes the content. You can link more than one tag library to a given page. One one page you might link tag libraries that do the following:

• Automate querying a database
  
  
• Let users send e-mail from the page
  
  
• Conditionalize the content based on one or more sets of conditions
  
  
3. Find the content that does not apply to all of the databases. For example, if the content only applied to Oracle databases, you would put the following syntax around the content:

   <cond:db db="oracle">Content that only applies to Oracle users</cond:db>

4. Find content that applies to two databases. For example, if the content applied to Oracle and SQL Server databases, but not MySQL databases, you would put the following syntax around the content:

   <cond:db db="oracle,sqlserver">Content that applies to Oracle and SQL Server users.</cond:db>

To see an example of conditionalization tag libraries in action, click here.

Using Scriptlets

If you know a little bit of Java, you can add scriptlets to your HTML or XML documents. Scriptlets embed Java functionality into your page.

Example: Repeating text a set number of times

Let's consider an end-user input form. You want your users to select a value between 0 and 52. In a form, you create a select box with these values:

<select name="select">
<option value="0">0</option>
<option value="1">1</option>
<option value="2">2</option>
...
<option value="52">52</option>
</select>

You have two options: you can hand-code the values 0 through 52, or, using JSP scriptlets, you could code your page to generate the same thing:

<select name="select">
<% for (int i=0; i<53; i++) { %>
  <option value="<%= i %>"><%= i %></option>
<% } %>
</select>

When the page is loaded, the end result is the same: the JSP scriptlet generates the same standard HTML that you would have hand-coded. Click here to open another browser window and see the output that the above code creates. When the page displays, choose the option on your Web browser that shows you the source code (View —> Source, in Internet Explorer).

More Ideas for JSP Tag Libraries

If you know a lot of Java, you can use JSP to do just about anything you can do with Java. The following are just a few ideas for tag libraries:

• Create an automatic glossary
  Automatically scans each HTML page and compares the words in the document to a list of words for which glossary topics have been defined. Then, it creates a pop-up link to the glossary term topic for each matching word. You could further enhance the function to link only the first occurrence of each term in each page.

• Track users’ navigation
  Learn what topics are visited most frequently, how long users typically spend reading a given topic, what path users take through the documentation, or when users go to the index or the table of contents. You could review this information when you prepare to revise the help system. The data could suggest the need for more links, an improved table of contents or index entries, shorter/longer topics, and so on.

• Automatically add reader feedback forms
  Automatically adds a form to the end of each topic. In this form, users could indicate how helpful the topic was, or what they're looking for, but cannot find. You could e-mail the data they enter in the form, or store it in a database.

• Enable users to request client-specific modifications
  Conditionalize content based on whether readers are from a specific company. This function lets a company modify the documentation for their users, without affecting other companies' users. This has the added benefit that the companies do not need to make their changes after every release, as the conditionalized content is carried forward from one release to the next.

• Provide color-coded versioning
  Provide a list of topics that were updated or added from one release to the next. When users visit these topics, the new or modified content is color-coded.

Using JSP Without Hosting on a Web Server

While you cannot take advantage of all that JSP has to offer when you create static HTML- or XML-based documentation that is delivered with your product (instead of loaded onto a Web server), you still can take advantage of some of its features. The following are the steps that you would perform to take advantage of JSP’s conditionalization capabilities.

To create customized HTML- or XML-based documentation:

1. Add the JSP customization code to your content.

2. Set up a Web server on your development computer (see “What Do I Need to Buy?” for more information on Web servers).

3. Obtain and install an application such as WebCopier or WebWhacker 2000. These applications download an entire Web site to your hard drive.

4. Create a JSP page that will allow you to specify the conditions that change what information is displayed in your documentation. This page would typically be a collection of check boxes and radio buttons that would let you specify the departments in which the end-users work, the types of end-users, the individual clients/customers, and so on.

5. Load the JSP page that you created in step 4 into your Web browser through your Web server.

6. Specify the conditions to create the documentation set your client/customer is requesting (for example, create documentation for managers in the Radiology department of St. Luke Hospital).

7. Using the Web site download application, download all of the files to another location on the hard drive. The version of the files the application downloads is conditionalized so that the files only contain information relevant to managers in the Radiology department at St. Luke Hospital.

8. Use the files from step 7 to create your HTML Help, WebHelp, or whatever form of HTML- or XML-based documentation you deliver with your product.

What Do I Need to Buy?

Developing JSP does not require that you purchase any software. All of the software you need to create JSP pages is free to download:

• The Tomcat Web server. This software is available at jakarta.apache.org.

• The Java Software Development Kit (SDK), version 1.1.8 or later. This software is available at java.sun.com.

• An HTML editor, such as Dreamweaver or FrontPage (as long as it isn’t one that “fixes” your source code when you’re not looking, such as earlier versions of eHelp’s RoboHTML). I highly recommend Dreamweaver 4. You can download a free 30-day trial of this product at www.macromedia.com/software/dreamweaver/download. If you don’t have an HTML editor and don’t want to buy one, you can use any text editor, including Notepad.

There are also many tag libraries that you can download for free, or that you can purchase. Some sources for these include the following:

• The Jakarta Project, at jakarta.apache.org/taglibs.

• The JSP Index, at www.jspin.com/home/tags.

Resources

I have searched for other Web sites that discuss using JavaServer Pages technology to enhance online documentation, but haven’t found any to date. The most helpful Web site that I can point you to is my own, jsp.davidcastro.com. If you need any help understanding or implementing anything from the site, please feel free to e-mail me at email@davidcastro.com.

Many books have been released in the past 6 months on the topics of JavaServer Pages. The only one that I can recommend from having read it myself (all the way through, even!) is Web Development with JavaServer Pages, ISBN: 1884777996. This book has just released a second edition, which you can download for only $17.00 at www.manning.com/fields2/ebook.html. I haven't read all of the second edition, yet. Others books that have been highly recommended on Amazon.com include Advanced JavaServer Pages, ISBN: 0130307041 and JSP Tag Libraries, ISBN: 193011009X.

You can create a small (5 MB or less) JSP-enabled Web site for free at www.mycgiserver.com. If you are looking for a hosting provider that will enable you to use a database and e-mail server, I highly recommend the provider that I use, www.mmaweb.net. They have a starter account for $25/month.

The free application WebCopier is available for download at download.cnet.com. WebWhacker 2000 ($50) has a free demo available for download at bluesquirrel.com. I have not yet used either of these applications, and I know that there are many more out there that can also perform the task of downloading an entire Web site to your hard drive. Try applications until you find one that works the best for your needs. If you feel like it, e-mail me and let me know which application you prefer.