AN INTRODUCTION TO ON-DEMAND, WEB-BASED PUBLISHING

Russell Ward

STC-PMC 2012 Conference – Willow Grove, PA

Agenda

Define concepts and benefits associated with web-based publishing

Demonstrate the installation and setup of a common web server, Apache Tomcat.

Demonstrate basic information delivery via the web server

Demonstrate the addition of more advanced, on-demand publishing features

Briefly showcase a real-world web-based publisher deployed at Spirent Communications that has provided substantial benefits

Q&A

Speaker contact information

Russ Ward

Senior Technical Writer at Spirent Communications in Germantown, MD.

Owner of West Street Consulting, a part-time enterprise specializing in Structured FrameMaker plugins and custom development.

20324 Seneca Meadows Parkway Germantown, MD 20876 301.444.2489 russ.ward@spirent.com www.spirent.com

357 W. North St. Carlisle, PA 17013 717.240.2989 russ@weststreetconsulting.com www.weststreetconsulting.com

Web-based publishing concepts

Before defining web-based publishing, it is useful to clarify the more commonly-used alternative: a distributed, file system-based documentation system that is normally static. Familiar examples include PDF, CHM, JavaHelp, Flash demos, etc. etc.

A static system uses some kind of viewer that draws information directly from a set of files, often stored on the same computer that is running the viewer.

Static systems are normally much less complex to implement, as many tools can generate them out-of-the box. Again, familiar examples include: • RoboHelp

• MadCap Flare

• Author-it

• Quadralay ePublisher

• The DITA open toolkit

• …and many more

Concepts (continued)

As an alternative, content can be “served” on demand by a dedicated application that interactively processes requests and responds as appropriate. Similar to any web-based operation, this type of uses:

• A web server – Some computer on some network somewhere that has information to hand out and “listens” for requests for that information.

• One or more client computers – The “consumers” of the information which request information from the server, usually with a web browser that subsequently renders the information.

There is always an exchange between two or more computers, usually facilitated by HTTP-based negotiations.

Web server

Concepts (continued)

Because of the inherent “server-side” processing capabilities, web-based publishing provides the following features and advantages:

• Dynamic adjustment of content based on the nature of a request

• Access control

• In some cases, an easier framework for swift content updates

• Normally no requirement to deploy software to users

• Opportunities for advanced functionality related to authoring and content management, such integration with collaborative authoring and source control systems

• Integration with any other system that supports web-based interactions; for example, corporate databases.

The possibilities are quite expansive. Any given capability may or may not be applicable to a certain situation.

Getting started

For a documentation system driven by a web server, you obviously need a web server. Two common options include:

• Apache HTTP Server /r Apache Tomcat – Free, open-source platforms that provide direct integration with native Java code (Tomcat)

• Microsoft Active Server Pages (ASP) – A commercial product that is more catered to integration with Microsoft-related technologies such as VBScript and ASP.net

This presentation will focus on Tomcat because:

• It is free yet very robust

• It runs anywhere (Windows, Linux, etc.)

• Your presenter knows much more about it than ASP

DEMONSTRATION Installing and starting up Tomcat

DEMONSTRATION Delivering simple, static content

Server-side processing concepts

Aside from remote network access, the real magic of delivering content with a web server is the expansive ability for server-side processing. You can effectively manipulate the content any way you want before sending it to the requestor.

The user does not necessarily see what is actually on the web server computer, only what the server application sends back. It may look like the user is receiving static HTML pages that are sitting on the server somewhere, but in actuality, the server may be dynamically generating the HTML code upon request.

In the case of technical documentation, server-side processing might include:

• Opening XML files and running XSLT transformations

• Querying some database for information

Basically, the server needs to do whatever is required to create the HTML for the client browser.

DEMONSTRATION A simple XML/XSLT setup for generating HTML

Server-side processing may be useful for generating content catered to specific users. For example, you could:

• Accept input from a user to apply the appropriate filters

• Use user profile information to otherwise adjust the content

For content reuse, the possibilities are endless. For example, you could:

• Apply filters using the “conditional text” model, according to some sort of input or selection criteria

• Pull common information from any central, networked location that supports web-based interaction, such as a database or file system

Profiling and content reuse

DEMONSTRATION Using XSLT to filter conditional content

DEMONSTRATION A mature, real-world system deployed at Spirent

Summary and final points

• Dynamic web-based publishing may not be applicable in all situations, but where it is, it can make all the difference.

• Most people would be surprised to know how much you can do for FREE (excepting your paycheck and that computer, of course).

• Web-based publishing requires knowledge in advanced concepts that take time to learn. If you want to develop an extensive and complex architecture, don’t expect it to be easy. Having said that, the rewards are worth every bit of effort and will make your resume look GREAT.

QUESTIONS