The following is taken from a proposal that I
wrote for my former employer. I have removed references to the company
name, and have modified some of the content to anonymize the material.
You should modify the content as necessary to make it apply more
to your company's needs.
There is mention of a web site that has JSP content
on it. This refers to the web site http://www.mycgiserver.com,
at which you can sign up for a free account. They provide you with
5MB of space, on which you can put JSP pages to make them available
to others to view. I don't believe that this account allows tag
Just for fun, I made the content on this page
dynamic. You can enter as many or as few values as you want in the
following. The fields you don't enter a value for will be represented
in the content with a bold phrase in angle brackets. Any information
you provide here is discarded after the dynamic page is generated.
You can leave all of the fields blank, if you prefer.
Tech Pubs Plans for JSP
The <Company Name> Tech Pubs department will begin implementing
JavaServer Pages technology in the documentation for the product
on <Start Date>.
The use of JavaServerPages (JSP) will allow
us to customize the documentation of our product for individual
users, based on the tasks they are responsible for, what modules
of the application they have access to, and what company they
The implementation of this technology is low-risk,
and could potentially be a profit-center for the company.
The requirements of other departments is very
minimal, and there is no requirement to purchase additional
hardware or development software, and there may not be a need
to purchase deployment software.
Initial rollout will take approximately four
writer-weeks, and additional functionality will be added in
What is JavaServer Pages technology?
You use JSP technology to create dynamic content on web sites (or,
in our case, in web-based documentation). JSP allows us to vary
the content in our documentation based on information that we collect
about our users and the companies that they work for. If you visit
any portals, such as www.yahoo.com, www.lycos.com, or home.netscape.com,
then you have seen dynamic content in action.
How will using JSP affect our documentation?
We have several plans for how to use JSP to make our documentation
more effective for our users.
We plan to provide customized content based on the following aspects
of the user who is accessing the Help:
ResponsibilitiesIs the user a <User Type 1>,
<User Type 2>, <User Type 3>, or mix of these three?
CompanyWhat company does the user work
DepartmentWhat department does the user
work in? We will be customizing the examples for different departments.
If a user works in <Department>, we will have <Department>-specific
examples. This will increase comprehension and shorten the learning
Available modulesWhich modules does
this facility have access to? We will customize the content
so that links to topics that require access to a module that
the user does not have are omitted.
Customizing content refers to changing what examples
are given, what links are included, which graphics are shown, what
steps are added or omitted, and so on. For example, if the user
is a <User Type 2> at <Sample Customer> reading the topic
about registering new patients, we would:
not include the link from that topic to the
topic on <Sample Task> (since the user is not a <User Type 1>).
change the table of contents so that it does
not show topics that only relate to the tasks that <User Type 1>
and <User Type 2> perform.
- customize content that lists required fields
for performing tasks so that it tells the user what fields are
required at <Sample Customer>.
A high percentage of our users are non-native
speakers of English. When users first access the Help in a given
workday, they will be prompted for the tasks they perform in the
system and for their preferred language. We will have glossary terms
translated into foreign languages on an as-needed basis. Having
glossary terms explained in their native language will help users
to understand the application better. If the demand exists, we may
even extend this to providing some of the more frequently-viewed
topics in the users native languages.
Current plans are to provide glossary terms with
both English and the users native languages to help them understand
the terms in English.
Without JSP, the only way to provide translated
glossary definitions would be to include all of the translations
with each glossary term, which would be cumbersome, at best.
We have segments of text that are common among
many topics. We will extract these text segments into separate files,
and then include them into all of the topics that need them.
Currently, the most widespread of these segments
of text is the description of how to use the date widgets in our
user interface. Currently, they indicate that you can enter the
date in M/D/YYYY or MM/DD/YYY format, type T for today,
or click the calendar icon. Recently, we found out that there are
several other shortcuts you can enter. If this information had already
been extracted into a separate file, we wouldnt need to go
into dozens of topics to change this. Instead, we could change in
in the external file, and it would be fixed everywhere.
We can purchase (for $100) a JSP tag library that
will turn glossary terms into pop-up links, automatically. All that
will be required of the writers is to enter a single line of text
at the beginning and end of all document pages in our help. Behind
the scenes, the JSP technology will find all of the words in each
document that appears in the glossary, and will insert the necessary
HTML to turn them into pop-up links. This will make maintenance
of the glossary much easier. When we add a term, it will automatically
be linked from all of the existing documentation.
Capturing reading path through topics
We can purchase (for $500) a JSP tag library that
will track our users' paths through the documentation. We can capture
the paths that users take through the documentation. Do they primarily
use the table of contents, the index, or hyperlinks? What topics
did they read in what order? How long did they spend in each topic?
We can then use this performance information to
add more hyperlinks between specific topics, modify the table of
contents and index, or possibly even spot trouble areas in the applications
graphical user interface.
What demands will implementing JSP require of other departments?
Implementing JSP will require remarkably little
of other departments. All that we need to successfully implement
JSP in our documentation is a Java servlet-capable web server (most
are), and the IP addresses of facilities that access the help (if
we opt to provide customer-specific documentation). All other customization
will be based on information that the users provide us when they
log onto the help for the first time each day, and the IP address
that the users hail from (which JSP can extract from the request
for the page).
What kind of training will using JSP require of the Tech Pubs
<Company Name>'s writers will be able to use
JSP technology in the documentation with little training. One of
the powerful features of JSP is called custom tag libraries. You
use custom tag libraries to enable a Help author to add functionality
to an HTML document with tags that are very similar to HTML tags.
There is no need to include Java code inside of our documents, so
maintenance of the documentation will not require a knowledge of
Java or JSP.
There is a free JSP training site, http://jsp.davidcastro.com,
that is geared specifically to technical writers using JSP. This
site provides the little training that we would need to successfully
implement JSP technology in our documentation.
Where can I see a working demo of this technology?
We have set up an account with a web host that
supports JSP. We will upload JSP demos to this account as they become
available. The URL for that account is:
How long will implementing JSP take?
The implementation of JSP in our documentation
will be performed in stages. The different ways that we will use
JSP are all fairly self-contained. That means that we dont
have to have everything implemented to start rolling out the enhancements.
We will be starting with customizing the content based on what modules
the users have access to. We already have a JSP tag library that
handles this customization; we merely need to apply the tag library
to our HTML files.
Additional functionality mentioned in this report
will be rolled out in the order in which Tech Pubs, Marketing, Sales,
Implementation, and Customer Support feel is best for the users.
Each of these additions are anticipated to be fairly short. The
one exception is the multi-lingual support. The timeline for this
functionality will also depend upon the turnaround time for professional
How could implementing JSP impact the company, financially?
One of the planned enhancements could be a profit-center
for the company. We can add, change, or remove content based on
the facility that the users work for. This customization would require
minimal time from the Tech Pubs staff, but would provide large benefit
to the facilities. It is common practice for a facility to take
a pass over documentation for the software they purchase, removing
shortcuts that they dont want their users using, adding steps
that they want their users to perform, and so on.
If we charge a per-topic fee to make documentation
customizations for facilities, then the facility will only need
to make the change once. Currently, they have to make these changes
and additions to the paper documentation with every release. Our
method will save them time and money. It will also allow them to
customize the online help once, and have those modifications reflected
in the Help not only for that release, but for all future releases,
Will implementing JSP require purchasing software?
Aside from installing a JSP-capable web server,
no. The fact that we have switched from using Blue Skys RoboHTML,
which we could not use to create JSP content, to Macromedias
Dreamweaver, which we can use, means that we do not have to purchase
additional software to make this technology work for us.
What risks are involved in implementing JSP?
The implementation of JSP in our documentation
is remarkably low-risk. The changes and additions that will be made
to the documentation files is easily removed or commented-out with
a simple search-and-replace.
Because the level of knowledge of Java and JSP
that will be required of the technical writers will be minimal,
staff turnover wont necessarily cause problems with continuing
to use the technology. The same is not true of other technologies
that embed programming or scripting language content in the documentation
There is a risk that some JSP functionality may
cause a page to not load correctly. Fortunately, JSP offers a way
to automatically redirect a user to an error page when a JSP page
has a problem. We can use this feature to redirect the user to a
generic, static HTML version of the page. It will mean that that
particular page wont be customized, but it at least will ensure
that all users will be able to access all of the Help, at all times.
We will include code in the redirect that sends the documentation
team an email indicating that there is a problem with the JSP page,
to expedite the solution to the problem.
There are no browser-incompatibility issues with
server. The actual JSP pages that are delivered to the users
browsers are standard HTML pages. In fact, switching to JSP will
make our documentation less susceptible to browser-incompatibility
Changes in the JSP technology wont invalidate
the work that we have completed. Sun is very strict in maintaining
backward-compatibility when they release new versions of technology.
If some change in the JSP technology causes functionality in our
web-based Help to stop working, it should be simple to fix, as the
JSP functionality isnt embedded in the individual topics,
but is rather extracted into external program files. We would modify
those external program files, which would fix any problems, help
If you have questions about JSP and how it will
affect our documentation, please feel free to contact <JSP Contact>
at <JSP Contact Email>.