Sell JSP

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 libraries, however.

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

Executive Summary

• 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 work for.

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

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.

Customized content

We plan to provide customized content based on the following aspects of the user who is accessing the Help:

• Responsibilities—Is the user a <User Type 1>, <User Type 2>, <User Type 3>, or mix of these three?

• Company—What company does the user work for?

• Department—What 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 curve.

• Available modules—Which 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>.

Multi-lingual content

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.

Boilerplate text

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 wouldn’t 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.

Automatic glossary

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 application’s 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 department?

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

http://www.mycgiserver.com/<mycgiserver Account>

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 don’t 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 translation.

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 don’t 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, too.

Will implementing JSP require purchasing software?

Aside from installing a JSP-capable web server, no. The fact that we have switched from using Blue Sky’s RoboHTML, which we could not use to create JSP content, to Macromedia’s 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 won’t 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 topics.

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 won’t 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 JSP, because, unlike JavaScript, all JSP processing happens on the 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 issues than it currently is, because we currently use JavaScript.

Changes in the JSP technology won’t 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 isn’t 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 system-wide.

Contact information

If you have questions about JSP and how it will affect our documentation, please feel free to contact <JSP Contact> at <JSP Contact Email>.