Adding Dimensions to Single-Sourced FrameMaker Projects
At ViaFone, we enjoy working in a single-source environment. However, our work environment was not always enjoyable. This article describes our situation before single sourcing, our transition to single sourcing, and some of the challenges that we encountered after moving to single sourcing.
Life before single sourcing
As we were going through a major product release in December 2000, new customer requirements (multiple platforms, new Help deliverables, and more) revealed the inadequacies in our existing documentation processes and techniques.
At that time, we were creating documents in multiple authoring environments, reusing a high percentage of information between the environments.
- Multiple authoring environments. We were authoring and producing information in two authoring environments:
- Corel VENTURA 8-let us create print and PDF documentation
- RoboHELP Office 2000-let us create online Help (.CHM files)
- If we reused any information between the two environments, we had to copy-and-paste it. If information changed, we needed to reflect the changes in source files of both environments.
- Document creation. We were creating documents; that is, we were creating user guides, install guides, and online Help. The information we authored and produced was not easily transferable between documents. For example, taking security information from the install guide and putting it in online Help was not easy to do.
Our requirements for single sourcing
Our team proposed a proactive approach to developing and delivering information-the redesign and retooling of our documentation system. The vision for the redesign and retooling included a single authoring environment and information creation.
- Single authoring environment. A single authoring environment would allow us to author and maintain information in one place. If information were to change, we would need to update a file only once.
- Information creation. In a single-sourcing environment, we would create information; that is, we would document features and functionality in chunks. These chunks would be discrete enough so that we could use the same information and reconstitute it into multiple documents such as user guides, install guides, and online Help. For example, we could take security information from the install guide and reuse it in online Help.
The single-sourcing solution needed to fulfill our requirements:
- provide a rich, powerful, easy-to-use authoring environment
- have industry support that is current and is easily accessible
- provide a cost-effective authoring environment
- chunk information into components small enough to reuse in multiple documents
- cross-reference and link information, keeping all references document-independent
- handle variables to let us change information globally, such as product names
- make text conditional for a specific reuse, for example, a different procedure for UNIX and Windows
- publish to multiple formats, including HTML, HTML Help, and PDF
Our single-sourcing solution
After investigating many single-source solutions, we proposed and implemented Adobe FrameMaker in conjunction with Quadralay WebWorks Publisher.
FrameMaker provided a powerful, cost-effective authoring environment. It let us chunk information into components in FrameMaker files and reuse them in multiple books. It let us cross-reference and link information, keeping all references document-independent. It had support for variables and conditional text. And it let us publish to PDF. WebWorks let us publish to HTML and HTML Help. Both tools had strong industry support.
We created templates for FrameMaker and transitioned our content to it. We created templates for WebWorks Publisher and produced our content using it. Since that time, we have had a major product release and a few minor releases. Overall, the single-sourcing solution is working as we planned.
During one of our recent projects, we had to expand the dimensions of a project from two conditions to eight. During that expansion, we experienced many challenges and devised some solutions.
OneBridge Mobile Professional is a personal information management (PIM) and messaging application that lets mobile business users access and use email, contacts, calendar, and tasks anywhere, at any time.
Its single-sourced documentation
Previously, Mobile Professional was available for one operating system: Microsoft Windows. On that operating system, the end user could install support for either the Microsoft Exchange or Lotus Domino mail provider server, but not both.
Therefore, we produced two installation guides-one for Exchange and one for Domino-from a single source. We made text conditional as either Exchange or Domino (see the table below).
Because only one condition could be applied at a time, this strategy worked.
Product Management noted a customer demand for another operating system (Sun Solaris) and additional mail provider servers (POP and IMAP). Users would install on only one operating system, but they could have any combination of mail provider servers.
Additionally, some features would be available only on certain combinations of operating system and mail provider server. For example, POP does not support tasks, so the tasks feature is available on Domino, Exchange, and IMAP (not on POP). Also, development could implement tasks on only Domino or Windows (not on Exchange, IMAP, POP, nor Solaris).
To support the new requirements, we had to add many other conditions (IMAP, POP, Windows, Solaris). In the case where a condition applied to more than one combination, we applied both conditions (see the table below).
We encountered two challenges:
- Adjacent conditional text. With more than two conditions, we could have nonsense sentences when we showed conditions. For example:
- Mobile Professional runs on OneBridge’s XMLEdge mobility platform and connects to the Microsoft ExchangeLotus DominoIMAP POP back-end messaging server.
- Conflicting conditions. The tasks feature was available on Domino on Windows only, but POP did not support it. When we wanted to create an installation guide for Windows, POP, and IMAP, we got conflicting conditions. For example:
- OneBridge Mobile Professional is a personal information management (PIM) and messaging application that lets mobile business users access and use email, and tasks anywhere, at any time.
- The Windows and POP conditions conflicted for the tasks feature. Tasks were available on Windows but not POP. In FrameMaker, if at least one of the conditions applied to a section of text is true, the text shows up. Because the operating system was true (Windows), the text showed up even though the feature was false (POP).
We solved the problems of conflicting conditions and adjacent conditional text in the following ways.
Fixing adjacent conditional text
We had to reorganize our information so that we could enable any or all of the conditions. We broke out our conditions so that they weren’t immediately adjacent to each other (see the table below).
Fixing conflicting conditions
When working with text that has multiple conditions, consider if the conditions are either
- Non-Exclusive–either condition can be satisfied for the text to display
- For example, if a section applies to either Windows or POP, apply both the Windows and POP conditions to the text. That way, if either condition is true, the text shows up.
- Exclusive–both conditions must be satisfied for the text to display
- For example, if a section needs both Domino and Windows to be true (as in the case of the tasks feature), create a new conditional name (such as “Domino and Windows”), and apply it to the text. That way, only if both conditions are true, the text shows up (see the table below).
Single sourcing has let us move from maintaining documents in multiple environments to maintaining information in a single environment. This transition has let us respond to ever-increasing customer demands for having superior documentation as well as organizational requirements for contributing to the bottom line.
We have encountered challenges in that transition, such as adding dimensions to an existing single-sourced project, but the benefits have far outweighed the challenges. We now produce administration guides for Solaris and Windows, with any or all of Exchange, Domino, POP, or IMAP mail provider servers, depending on our customer. If we need to provide additional dimensions to our documentation, we can do so using the strategies that we developed.
About the Author