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.
|