JavaServer Pages for Technical Writers

This article doesn't aim to teach you how to use JavaServer Pages (JSP), but rather to show you what technical writers can do with it. For information on how to use JSP to enhance your web-based documentation, see http://jsp.davidcastro.com.

What is JavaServer Pages?

JavaServer Pages (JSP) is a relatively new technology introduced by Sun. Similar to Active Server Pages from Microsoft, JSP enables you to create dynamic HTML pages. This type of dynamic HTML is not the same thing as "Dynamic HTML" (DHTML). In this case, what it refers to is the ability to customize individual pages by incorporating information from other pages, from database queries, from user input, from calculations, from custom tags, and so on.

What can JSP do for technical writers?

JSP is the answer to the age-old question, "How can I create documentation that is easy to maintain, that allows my users to 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 doc, and that doesn't require plug-ins?"

How is JSP different than ASP?

The answer to this question has changed recently, with the introduction of ASP+. ASP+ is a new form of ASP that will run on the .NET platform. ASP+ has integrated several features and benefits of JSP. The following comparison compares standard ASP and JSP.

JSP allows you to separate the functionality of a site from the content. When you use all of what JSP has to offer, you do not have to embed code into your HTML pages, as you do with Active Server Pages. This separation allows each person working on the project to work on what he or she knows about. Java programmers can work on the Java functionality; writers can work on the content. Of course, if you happen to both be a writer and a Java developer, you can do both, but it isn't mandated by the technology.

There are many other ways that JSP differs from ASP, such as performance (JSP is precompiled, while ASP is compiled each time the page is requested), portability (Java's write-once-run-anywhere), and more, but as far as writers are concerned, the most important difference is the separation of web site logic from web site content.

How do you create customized content with JSP?

JSP supports a powerful feature called tag libraries. Tag libraries allow you to package Java programming functionality into HTML tags that you can then use in your HTML files. These tags are read by the web server that sends the page to the user, and they perform some function. They might:

  • import an external page into the current page (boilerplating)

  • make a call to a database to retrieve information specific to the current user

  • check to make sure that the user has logged in before presenting the page

  • filter the content so that only the information that is appropriate for the user is displayed

  • display the results of a calculation based on information the user has entered

For example, I am using JSP in the documentation for an Application Service Provider. This particular application provides web-based scheduling functionality to medical facilities. There are three roles that a user might perform in the application: scheduling appointments, registering patients, or administering the system. Some users perform more than one of these roles. In the section of the documentation that explains registering patients, there is a link to a topic that explains how to set up address types. If a user performs both registration and administration roles, this link would be helpful. But if the user is only a registrar, then this link is distracting.

So, we created a tag in the tag library that filters the content based on the roles that the user performs. In our case, we created a tag that lets you specify that content is included or excluded based on whether the reader is a scheduler, a registrar, or an administrator. The actual HTML that uses these tags looks like this:

<%@ taglib uri="/scheduling" prefix="sched" %>
<HTML>
<BODY>
...
<P>Select an address type from the list. <sched:Role type="administrator" action="include">
You set up address types using <a href="Code_files.htm">code files</a>.</sched:Role></P> ... </BODY>
</HTML>

There are two important parts of this code segment. The first line specifies that the JSP file uses a custom tag library. The URI indicates where to look for the configuration file for the library, and the prefix indicates how the HTML tags that use the tag library will appear in the HTML file. The tag that begins <sched:Role... uses the tag named "Role" in the custom tag library. The Role tag looks to see what kind of user is requesting the page (this information was collected when the user originally logged into the system), and only displays the link if the user is an administrator.

If the user is an administrator, this is the HTML that is sent to her browser:

<HTML>
<BODY>
...
<P>Select an address type from the list. You set up address types using <a href="Code_files.htm">
code files</a>.</P>
...
</BODY>
</HTML>

And if the user is not an administrator, this is the HTML that is sent:

<HTML>
<BODY>
...
<P>Select an address type from the list.</P>
...
</BODY>
</HTML>

Processing happens at the server

One beneficial side effect of the way JSP works is that standard HTML code is sent to the browser. You don't have issues with browser compatibility, as you do when using JavaScript or DHTML. Also, the user can't look in the HTML page's source to find the information that she isn't supposed to see. The filtering happens at the web server.

Make your documentation a profit center!

Certain types of customers like to make modifications to the documentation their employees use. Medical facilities often have regulations that contradict what the documentation for a product says. For example, if the topic covering patient registration says that you can enter a patient with nothing more than the patient's last name, but the medical facility requires full name, insurance information, contact information, and so on, they will want to make modifications to the documentation. If you handle these modifications with a custom tag, then the changes they make get carried forward with future versions of the application. No more requiring your customer to make the same changes release after release. This labor savings for your customer can turn into a way for your company to make money. Charge a per-word, per-page, or per-hour fee for making these changes. You can even set up an interactive form on your site to make it easier for your customer to get those pages incorporated.

Where can I get more information?

More and more web sites discussing this technology are popping up every day. Some of the more well-known web sites include:

There is also a mailing list that covers this subject. You can search its archives at:

And you can join the list at:

The following are a some FAQs on the subject:

If you have any questions that these resources don't answer, feel free to contact me at email@davidcastro.com.


Page last modified 06/14/2002