Automating Single-Source Development

CIDM

December 2004


Automating Single-Source Development


CIDMIconNewsletter Andrew VanConas, Vice President of Consulting Services, Quadralay Corporation

In today’s competitive and fast-changing environment, software companies are updating, revising, and delivering their software-based products many times during the year-a development that might have seemed impossible six to ten years ago. Since that time though, software development has evolved and the ability to release software has improved due to several factors-version control systems, content management systems, and the reusability of code, to name a few.

The increased pace of software development has also had an effect on the process of developing and delivering documentation (content). As a result, content providers must decrease the time required to complete their information-development processes, such as gathering information, maintaining the current content, authoring the new content, reviewing the content, building the online help system, delivering the help system for the next software build, testing the context-sensitive calls used in the software, creating PDFs, and finally, releasing the online help system as part of the software product. Following are several timesaving guidelines and methods to enhance and simplify the content provider’s single-sourcing efforts.

Content

For a content provider, it all starts with the content. Each group of content providers has a preference as to which authoring environment they choose and many reasons why they select one over another. For example: the selection may be governed by ease of use, by the need to comply with company standards, or it simply may be based on what they know how to use. To meet shortened product release cycles, providers need an authoring environment that is easy to learn and implement, provides for multiple authors, can assist them in converting content into several online formats, is unobtrusive to an edit-and-review cycle, and is cost-effective.

What is the best authoring environment?
Content can be written in just about any authoring environment from text files to a highly customized XML-based solution; the selection of an authoring environment is one of the most important decisions a writing group will make. If the plan is to obtain a single-sourcing solution, the content should be developed in such a way that it is reusable, provides conditional-text support, and has a seamless edit-and-review life cycle.

One solution, and the one recommended here, is to author the content in either Microsoft Word or Adobe FrameMaker (structured or unstructured) and then use another set of tools to enable the edit-and-review cycle and to automate the publishing to multiple formats such as print, PDF, online help, and HTML for the Web. In addition, authoring the content with either of these editors allows for the reuse of information and the sharing of content. Another advantage of this approach is that most, if not all, content providers are proficient in either Word or FrameMaker and will not require additional training.

To maximize your success with this solution, you will need a well-designed source template that contains a catalog of paragraph, character, and table style definitions, along with at least a few conditional text settings. The more effort devoted to the design of a well-formed source template, the more time you and your group will save later during the project and over the lifetime of the content.

Once you have the authoring environment and a source template defined, you can then concentrate on content creation, conducting reviews, converting to online formats, and even using revision control or content management solutions to record and track all your content.

Now you must decide if a single-sourcing approach is for you and your organization.

Here are a few questions that might help make this decision easier. Would you like to have certain content available to different audiences-for example, a system administrator, an associate, a manager, or another employee? Does your content need to be deployed in more than one format-for example, as printed manuals or online help? Do you provide an OEM solution to other companies, where the documentation delivered must be changed for each customer? Any positive answers to these questions are signals for the use of conditional text and/or variables that both Adobe FrameMaker and MS Word support (the WebWorks plug-in is required for MS Word).

Traditional Documentation Life Cycle

Most traditional documentation life cycles start with creating, writing, or maintaining content. Once the content is created or written, then an edit-and-review cycle is started; the cycle finishes with production of the content prior to release or delivery. The most important timeline for content providers is the content creation. Therefore, anything that maximizes this timeline is a good thing that gives you more time to create and maintain the content. (See Figure 1.)

Writecycle fig 111

Figure 1. Traditional Documentation Life Cycle

During the edit-and-review cycle, in some cases, the content is frozen and cannot be edited until all of the reviewers’ comments have been received. This shortens the content creation timeline. The review can be performed via hard copy, PDF, or email; all of which are manual processes and consume time.

Another process that shortens the timeline for content creation is the final series of steps that occurs during the production of the content, where the material is converted to an online format, printed, and in some cases converted to PDF. Once again, this is a manual process that takes considerable time and can be error-prone. Not only that, during this time minor changes to the software product can have a major impact on the content, which may lead to yet another edit-and-review cycle and reproduction of the content. This process is outdated, time-consuming, and does not improve the content creation timeline. How can we reduce the impact of these steps in the process?

Edit and review
Once the content creation has begun with adherence to the source template and with conditional text and variables applied, you need to have the content reviewed by Subject Matter Experts (SMEs). SMEs are very busy, as we all are, and reviewing content is not their principal duty. Therefore, we need to make this effort as painless and efficient as possible. This is where Quadralay’s newest product, WebWorks FinalDraft, comes into play. FinalDraft is an online edit-and-review tool that allows SMEs to easily review content and provide feedback to the content provider. FinalDraft facilitates the edit-and-review process by allowing the content provider to choose the reviewers of the content and which content is to be reviewed. In addition, it provides complete integration with many e-mail programs for the distribution of the review.

Writecycle fig 29

Figure 2. Edit and Review Process

WebWorks FinalDraft allows reviewers to quickly review content and also share discussions, not only between reviewer and content providers but also with other reviewers, using its intuitive, browser-based interface. The content provider moderates the discussions, sets status codes, and also relates the comment/discussion entries to their locations in the source file. With the use of WebWorks FinalDraft, the reviews occur during content creation, not afterward. Therefore, there is no need to freeze the content for a review; in fact the content creation cycle is extended, which means more time to write.

Not only is the content creation cycle extended with the use of FinalDraft, the time required for this process is reduced because a consistent and comprehensive review of content is produced without any extra effort. Results from companies using WebWorks FinalDraft indicate the edit-and-review cycle has enhanced the content because it is thoroughly reviewed and information is fully shared throughout the team.

In addition, WebWorks FinalDraft is easy for both reviewers and content providers to use. In fact, several companies have implemented WebWorks FinalDraft in their engineering group for reviews of design documents, statements of work, and other engineering content.

Tammy VanBoening of NetRegulus says, “I use WebWorks FinalDraft. It’s a totally email based tool that does not require the users to have FrameMaker, Word, or Acrobat. It’s really slick and my SMEs have been very happy.”

Production automation
The most time-consuming step in the single-sourcing life cycle is the production of the final content in its desired format. I have experienced production cycles of three weeks or more during my career as a content provider. This is a very important time for every company: Engineering is placing the final touches on the software product and Quality Assurance is performing the final testing, which may include testing of context-sensitive help calls. All of these efforts have a direct impact on the content. This also is a busy time for content providers, who may be incorporating late changes, sending these out for a quick review, reconverting the content to its online format, re-creating PDFs, and sending the content out for printed manuals.

Writecycle fig 310

Figure 3. Production Automation

The goal is to automate as many of these production processes as possible, similar to the way software builds are automated. Once accomplished, the automation leads to more time to develop content. The only product on the market that can automate the conversion of either Adobe FrameMaker or MS Word content to an online format is WebWorks AutoMap.

WebWorks AutoMap automates the conversion of source files into most online formats like HTML, XML, HTML Help, Sun Java Help, Oracle Help for Java, and a cross-browser, cross-platform help system-WebWorks Help. Using WebWorks AutoPDF, an add-on to WebWorks AutoMap, you can convert your content into PDF automatically; no manual setup is required.

One of the key features of WebWorks AutoMap is the scheduling of online conversions, which can occur daily, weekly, or along with a software build. By having a scheduled process that requires no manual intervention each time it runs, WebWorks AutoMap minimizes the production time and extends the content-creation timeline.

Furthermore, WebWorks AutoMap has the functionality to show and hide conditional text and change the values of variables, which are essential for successful single-sourcing. At Quadralay, we have two products, WebWorks Publisher 2003 for Word and WebWorks Publisher 2003 for FrameMaker. The products are very similar; one converts MS Word content and the other converts FrameMaker content. When we started planning for the new release of WebWorks Publisher, we did not want to create or maintain two separate sources that would have similar content. In addition, content from a previous release was created in FrameMaker, and we planned to reuse some of that content for the new release.

In our source template, we defined conditional text settings for each product (Word-only and FrameMaker-only) and several different variables for product names and other product-specific terms. During the creation of the content, we created two WebWorks AutoMap jobs, one for WebWorks Publisher 2003 for Word and the other for WebWorks Publisher 2003 for FrameMaker. We defined a WebWorks AutoMap job with the Word-only conditional text to show and the FrameMaker-only to hide, along with changing variables to reflect WebWorks Publisher 2003 for Word.

In the second WebWorks AutoMap job, we switched the conditional text to hide the Word-only and show the FrameMaker-only and also changed the variables to reflect WebWorks Publisher 2003 for FrameMaker. Each job was scheduled to run at midnight and the converted online help was placed in separate directories. We also worked with our engineering team to have both WebWorks AutoMap jobs become part of the software build.

In previous releases, we waited until late in the production cycle to incorporate the online help, which sometimes delayed the release of the software due to broken context-sensitive calls or last-minute software changes that caused the content to change; we then had to reconvert the content into online help and incorporate it into the software. With the new process in place, we were able to identify broken context-sensitive links earlier in the process, and we no longer had to manually place the online help into the software. The result is two separate products with two separate online help systems that are from the same source, while our production time went from two weeks to two days-single-sourcing heaven!

Version control integration
Our Development Manager and I were discussing this great system we had created using AutoMap and how much valuable time it saved the engineers and the writers, resulting in our shipping the product ahead of schedule. We started thinking about how we could improve this process, by using either a version control or a content management system to store the source files and the converted online help files, both of which WebWorks AutoMap supports. Prior to the scheduled conversion, WebWorks AutoMap checks the source files out to a location on a server, then converts the files to the online help system. When the conversion is complete, AutoMap checks the online help system in to the version control system. Finally, the software build is run and we can deploy a fully functional software product with online help with a single day’s notice.

Writecycle fig 417

Figure 4. Version Control Integration

With our automated single-sourcing system, we can update our online content daily. We have reduced our production time from two to three weeks down to one day, which equates to more time to develop content. Our content is more complete than ever, thanks to comprehensive reviews, and the reuse of information frees our content providers to write new content. This system has enabled us to find and correct errors in either the content or the online information almost instantaneously. The engineers no longer manually copy the online help into the software and then test the context-sensitive help calls. Overall, our automated single-sourcing system has kept our content in pace with software development and together we are able to get our products to market faster. CIDMIconNewsletter

About the Author

Van Conas photo b-w28