Looking for something?
By Rob Hanna, Toronto Chapter President
Like many of you, I've struggled over the years to find the right combination of tools and processes to reliably manage large volumes of volatile text under the duress of seemingly impossible deadlines. Inevitably, I had to learn to customize my tools and automate as much of the process as I could. This meant getting under the hood and learning numerous scripting and markup languages. I was constantly exploring new technologies and applications that could take on some of the heavy lifting.
During my last engagement as a technical communicator, I started to gain a real appreciation for an authoring tool I had only flirted with previously — Adobe FrameMaker. Over the course of several publishing cycles, I was able to cobble together a pretty reliable single-source publishing solution. With FrameMaker at the heart of my process, I found that I could reuse my content by going to a more modular style of writing and use text-insets and conditional text for singlesourcing. I found I could also repurpose my content across several different output formats. The only problem was that I couldn't automate the process with FrameMaker alone. I had to strap on many different applications to my process to manage my content.
Parts of the publication process couldn't be automated with the tools we had on hand. I used a code management tool to store and version my content. I used a spreadsheet to record and manage metadata for that content. I used scripts to bring together content I needed for publishing. There were also problems with FrameMaker that I had to find workarounds for such as embedding updateable cross-references between content in text-insets; fixing broken paths to images and files; and managing complex conditions for publishing.
Another major problem area for our process was with collaboration. Over the course of my engagement the volume of work and the accumulation of overtime forced our team to grow from a single technical communicator to a team of four. If one of us stepped out of process it would set us back while we tried to find out what went wrong. Because we were working on smaller pieces of content, we could all work together without locking up the whole document. But we also ran the risk of misplacing or mislabeling pieces of content. If the spreadsheet wasn't updated regularly, we would end up repeating tasks unnecessarily or risk creating a large bottleneck when it came time to aggregate the content at publishing time.
Getting content from our subject matter experts was no walk in the park either. They were under their own deadlines and had no appreciation for the time pressures we were in sitting at the tailend of the product life-cycle. Every so often they would find time to get their content to us but rarely ever within the timeframe we asked for it. It would come to us in different formats that we would have to convert to FrameMaker and lay out ready for publication. We then had to convert it to RTF and send it back for approval and then go through the conversion process once again to get their corrected text back into FrameMaker. It wasn't nearly as efficient as it sounds.
We tried purchasing tools to automate the working with FrameMaker but this was no simple task. Every upgrade to either the add-on tool or to FrameMaker meant we had to rewrite our scripts or change our processes. In a couple of cases we had to back out of an add-on upgrade or abandon the new add-on all together.
Just as things were beginning to come together and the process was approaching maturity, we encountered another major twist. Greener pastures were calling me away. I ended up leaving my team holding my bag of tricks which consisted of a lot of complex scripts and processes all held together with shoe strings and chicken wire.
There is a happy ending to my story. I eventually found a solution to most of the challenges I faced-by becoming part of the solution with a company called SiberLogic. This company has been producing an XML-based content management system (CMS) since 1999 specifically targeted at the technical communication market. With their tool, SiberSafe CMS, we have been able to address virtually all of the bumps on the road to automated single-source publishing with FrameMaker.
SiberSafe can replace all your FrameMaker plug-ins. It is the one endto-end solution that takes you from the initial writing assignment straight through to multi-channel publishing of your source content, ensuring that you are more productive on an ongoing basis and more responsive to ad hoc requests.
I no longer need to maintain spreadsheets of metadata or a bloated code management tool stuffed with FrameMaker files. The content management system stores the metadata, and content is checked directly into and out of FrameMaker so that the team no longer needs to worry about stepping on someone else's work. File naming conventions and complex directory structures became a thing of the past. Writing assignments are sent out through email and managed by the workflow engine in the CMS. Each writer has a list of writing tasks and knows how and when to execute them, and managers can keep track of progress and resource allocation.
Content is easily found and reused from the repository. I can define the granularity of reuse appropriate for our workflow and use it knowing that it will be updated appropriately across all instances when I publish it. Links are managed by the CMS and strictly enforced each time content is taken out of the repository. Even links to embedded images and other binary content are rebuilt by the system upon publishing. Because there are no broken links, I save a lot of QA time and the final product is higher quality.
Using the conditional inclusion features in the CMS instead of the conditional markup in FrameMaker I can specify complex conditions for my content to produce custom versions of my publications. The CMS uses attributes set on elements in my structured FrameMaker content ensuring that the DTD won't break when the conditions are applied.
With SiberSafe's online web-based editing console, subject matter experts can contribute content directly through their web browser without even knowing that they are using XML, or even FrameMaker. This can be particularly useful when contract assistance is required and FrameMaker expertise is limited. They are sent a task from SiberSafe via email from where they launch the appropriate template in the editing console, complete their content, and submit it directly to the repository. The automated workflow ensures that the task can be escalated to a manager if the contributor fails to respond to the assigned task within the defined timeframe.
Presentation style is no longer an issue for authors and contributors with a flair for "font-fiddling." Styles are applied directly to the XML upon publishing instead of being applied inline within the FrameMaker file. In fact, we can have many different presentation styles applied to the same FrameMaker content.
Once the team has the content in the system, they submit the content to assigned reviewers through the workflow engine. The online reviewing console allows reviewers to add annotations to the text and see other annotations in real time within their collaborative reviewing environment. When they are finished, the workflow sends it to me to dispose of the comments accordingly.
If you translate your content, SiberSafe will manage this too. The automation in the workflow triggers translators to translate only changed fragments of content thereby reducing the amount of content that needs to be processed, saving both time and money. SiberSafe's translation memory feature allows you to aggregate translation memory files into a single federated translation memory file. SiberSafe even ships with an integrated translation memory tool that you can use if you do not already have one.
Once all of the content is safely to bed, I use SiberSafe's publishing engine and staging application to produce any of my target information products. These can be PDF, HTML Help, Web Help, RTF, WEP, PDA, etc. I can even choose to send my output to SiberSafe's standalone knowledge base format. I also have the flexibility to choose any structured application for new documents. While it can be configured for any DTD or schema, SiberSafe has out-of-the box support for such documentation standards as DocBook, sdocbook, the Darwin Information Typing Architecture (DITA), and S1000D.
But one of the most amazing aspects of this solution is that I can perform most of these tasks directly from FrameMaker. With SiberSafe's new FrameMaker integration, most of the authoring tasks can be accessed through menus and context-sensitive commands directly in FrameMaker. This effectively reduces the complexity of my process down to a single tool, so I can do much more-with less! As all of the business rules are programmed directly into SiberSafe, I'll no longer have to leave my team holding the bag when it's time to step off into my next big adventure.
Rob Hanna can be reached at rob dot hanna at ascan dot ca.
Rob Hanna
During my last engagement as a technical communicator, I started to gain a real appreciation for an authoring tool I had only flirted with previously — Adobe FrameMaker. Over the course of several publishing cycles, I was able to cobble together a pretty reliable single-source publishing solution. With FrameMaker at the heart of my process, I found that I could reuse my content by going to a more modular style of writing and use text-insets and conditional text for singlesourcing. I found I could also repurpose my content across several different output formats. The only problem was that I couldn't automate the process with FrameMaker alone. I had to strap on many different applications to my process to manage my content.
Parts of the publication process couldn't be automated with the tools we had on hand. I used a code management tool to store and version my content. I used a spreadsheet to record and manage metadata for that content. I used scripts to bring together content I needed for publishing. There were also problems with FrameMaker that I had to find workarounds for such as embedding updateable cross-references between content in text-insets; fixing broken paths to images and files; and managing complex conditions for publishing.
Another major problem area for our process was with collaboration. Over the course of my engagement the volume of work and the accumulation of overtime forced our team to grow from a single technical communicator to a team of four. If one of us stepped out of process it would set us back while we tried to find out what went wrong. Because we were working on smaller pieces of content, we could all work together without locking up the whole document. But we also ran the risk of misplacing or mislabeling pieces of content. If the spreadsheet wasn't updated regularly, we would end up repeating tasks unnecessarily or risk creating a large bottleneck when it came time to aggregate the content at publishing time.
Getting content from our subject matter experts was no walk in the park either. They were under their own deadlines and had no appreciation for the time pressures we were in sitting at the tailend of the product life-cycle. Every so often they would find time to get their content to us but rarely ever within the timeframe we asked for it. It would come to us in different formats that we would have to convert to FrameMaker and lay out ready for publication. We then had to convert it to RTF and send it back for approval and then go through the conversion process once again to get their corrected text back into FrameMaker. It wasn't nearly as efficient as it sounds.
We tried purchasing tools to automate the working with FrameMaker but this was no simple task. Every upgrade to either the add-on tool or to FrameMaker meant we had to rewrite our scripts or change our processes. In a couple of cases we had to back out of an add-on upgrade or abandon the new add-on all together.
Just as things were beginning to come together and the process was approaching maturity, we encountered another major twist. Greener pastures were calling me away. I ended up leaving my team holding my bag of tricks which consisted of a lot of complex scripts and processes all held together with shoe strings and chicken wire.
There is a happy ending to my story. I eventually found a solution to most of the challenges I faced-by becoming part of the solution with a company called SiberLogic. This company has been producing an XML-based content management system (CMS) since 1999 specifically targeted at the technical communication market. With their tool, SiberSafe CMS, we have been able to address virtually all of the bumps on the road to automated single-source publishing with FrameMaker.
SiberSafe can replace all your FrameMaker plug-ins. It is the one endto-end solution that takes you from the initial writing assignment straight through to multi-channel publishing of your source content, ensuring that you are more productive on an ongoing basis and more responsive to ad hoc requests.
I no longer need to maintain spreadsheets of metadata or a bloated code management tool stuffed with FrameMaker files. The content management system stores the metadata, and content is checked directly into and out of FrameMaker so that the team no longer needs to worry about stepping on someone else's work. File naming conventions and complex directory structures became a thing of the past. Writing assignments are sent out through email and managed by the workflow engine in the CMS. Each writer has a list of writing tasks and knows how and when to execute them, and managers can keep track of progress and resource allocation.
Content is easily found and reused from the repository. I can define the granularity of reuse appropriate for our workflow and use it knowing that it will be updated appropriately across all instances when I publish it. Links are managed by the CMS and strictly enforced each time content is taken out of the repository. Even links to embedded images and other binary content are rebuilt by the system upon publishing. Because there are no broken links, I save a lot of QA time and the final product is higher quality.
Using the conditional inclusion features in the CMS instead of the conditional markup in FrameMaker I can specify complex conditions for my content to produce custom versions of my publications. The CMS uses attributes set on elements in my structured FrameMaker content ensuring that the DTD won't break when the conditions are applied.
With SiberSafe's online web-based editing console, subject matter experts can contribute content directly through their web browser without even knowing that they are using XML, or even FrameMaker. This can be particularly useful when contract assistance is required and FrameMaker expertise is limited. They are sent a task from SiberSafe via email from where they launch the appropriate template in the editing console, complete their content, and submit it directly to the repository. The automated workflow ensures that the task can be escalated to a manager if the contributor fails to respond to the assigned task within the defined timeframe.
Presentation style is no longer an issue for authors and contributors with a flair for "font-fiddling." Styles are applied directly to the XML upon publishing instead of being applied inline within the FrameMaker file. In fact, we can have many different presentation styles applied to the same FrameMaker content.
Once the team has the content in the system, they submit the content to assigned reviewers through the workflow engine. The online reviewing console allows reviewers to add annotations to the text and see other annotations in real time within their collaborative reviewing environment. When they are finished, the workflow sends it to me to dispose of the comments accordingly.
If you translate your content, SiberSafe will manage this too. The automation in the workflow triggers translators to translate only changed fragments of content thereby reducing the amount of content that needs to be processed, saving both time and money. SiberSafe's translation memory feature allows you to aggregate translation memory files into a single federated translation memory file. SiberSafe even ships with an integrated translation memory tool that you can use if you do not already have one.
Once all of the content is safely to bed, I use SiberSafe's publishing engine and staging application to produce any of my target information products. These can be PDF, HTML Help, Web Help, RTF, WEP, PDA, etc. I can even choose to send my output to SiberSafe's standalone knowledge base format. I also have the flexibility to choose any structured application for new documents. While it can be configured for any DTD or schema, SiberSafe has out-of-the box support for such documentation standards as DocBook, sdocbook, the Darwin Information Typing Architecture (DITA), and S1000D.
But one of the most amazing aspects of this solution is that I can perform most of these tasks directly from FrameMaker. With SiberSafe's new FrameMaker integration, most of the authoring tasks can be accessed through menus and context-sensitive commands directly in FrameMaker. This effectively reduces the complexity of my process down to a single tool, so I can do much more-with less! As all of the business rules are programmed directly into SiberSafe, I'll no longer have to leave my team holding the bag when it's time to step off into my next big adventure.
Rob Hanna can be reached at rob dot hanna at ascan dot ca.
Top of page
Staff and authors:
