Posts Tagged ‘framemaker’

What is a Structured Document?

Monday, March 22nd, 2010 - Posted By: John Crews

This is a question commonly asked by our customers when we begin working with them on a single-source solution.  There is a short answer:

A structured document organizes paragraphs (elements) in a logical hierarchy, provides a means to attach tags (attributes) to individual paragraphs (elements), and gives you the ability to view the document in multiple ways.  FrameMaker ® (and other editors) also gives you the ability to manipulate the content of structured documents so that you can supply different outputs from the same document.

For this discussion, I will be using Adobe® FrameMaker® as my editor.  FrameMaker’s what-you-see-is-what-you-get view of structured documents is called the Document View.  If you have worked in unstructured Frame, this should look very familiar:

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Note, that all text is enclosed in brackets.  These brackets indicate element boundaries on the WYSIWYG view (Document View).  This correlates to the Structure View hierarchy described later.

The second way to view the document is called Structure View in FrameMaker.  The Structure View shows all elements (paragraphs) arranged in a hierarchy.  Each box represents an element.  An excerpt of the element text is displayed to the right of the element.  Below each element are Attributes assigned to the element.

The example highlighted below shows that the first element Bullet1 is assigned a value of 1 for the attribute Output.  The second element Bullet1 is assigned a value of 2 for the attribute Output.

In addition to managing the attributes and hierarchy of elements, you can also perform some edits in the Structure view.  If you right-click on an element, a context menu appears that describes several possible actions.  Typical shortcut buttons (ctrl+C for copy, ctrl+v for paste) function normally.  You can also drag-and-drop elements to move their location or to change their place within the hierarchy.

Most users who are accustomed to unstructured FrameMaker are used to working with the formatting toolbar.  Structured Frame does have this functionality; however, it also introduces an Element Catalog in place of the paragraph catalog.  The Element Catalog lists elements that may be selected to insert into the document and provides a tool-set for managing elements as you create them.  Using this catalog, you can insert an element into an existing element, wrap an existing element inside of a new element, and change the type of an existing element.  This tool set helps to minimize the complexity of managing the content from the Structure View.

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Once you have an element in place, you can assign attributes using the Attribute Editor.  The editor displays potential attributes for a selected element and lists the predefined values that may be assigned.  Select the desired attribute, assign an attribute value, and then select the Set Value button.  This assigned value is then visible in the Structure View.

 

 

 

 

 

 

 

 

 

 

Using the Structured FrameMaker tool set helps to make management of complex single-sourced documents easier.  Creating a functional hierarchy allows you to manage content at all levels.  Attributes allow you control several output levels and types while ensuring that you are able to maintain accurate content.

Tags: , , , , , , , , , , , , , , , , , , ,
Posted By: John Crews | Post a Comment! »

Import Images by Reference – Advil for Drawing Revision Headaches

Wednesday, March 10th, 2010 - Posted By: John Crews

Our Customers Ask…

“Our company frequently revises our engineering drawings.  Several of these drawings are included in our product guides.  How can we efficiently ensure that the latest drawings are included in our manuals?”

PPI Answers…

We use a repeatable method to ensure that our customers’ latest drawings are always included in documentation.  The key lies in the way we import images.

When you insert a drawing into an Adobe® FrameMaker® document, you have the option of either embedding or referencing the image file.  If you select the embed option, the file is imported as a static part of the document.

Instead, selecting the Import by Reference option tells FrameMaker® to check the source file each time you open the document.  This means that if you change your drawing, save it in the same location by the same name, then FrameMaker® will display the updated image next time it opens the document. 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Voila! Automatic drawing updates!   The tricky part is building a sustainable file structure that allows you to manage the images while retaining revision control.  Most organizations use the name of their drawing files to track revisions.  This can still be done while setting up a file structure that promotes referencing vs. embedding image files.

 A common file structure might look like this:

Each file name includes a brief description of the file and shows what revision.  Users can tell at a glance what file is the latest revision.

 In order to make the best use of the Import by Reference option, you might consider adding an Active folder to your file structure.  The files in the Active  folder should not have the revision information in the title.  For example

 

 

When you update a drawing, follow these steps;

  1. Save the file as you normally would.
  2. Save a copy of the drawing to the Active folder
  3. Rename the file so that it has the same name as the previous revision.  This way, FrameMaker knows what drawing files should be displayed. 

Managing your files this way saves you the nightmare of hunting through existing documents and replacing images every time a drawing is revised.

Tags: , , , , , , , , , , , , ,
Posted By: John Crews | Post a Comment! »

Conditional Formatting vs. Attribute Filtering in Single-Sourced Documents

Friday, March 5th, 2010 - Posted By: John Crews

Many of our customers come to us because they see the value in single-sourcing their documentation.  Of couse it is simple and cost-effective to maintain a single document that provides multiple outputs – much simpler than trying to juggle multiple individual files. 

When designing the single-source document, one of the first considerations has to be how you will manage the content.  To this end, there are two primary methods:  Conditional Formatting and Attribute Filtering.  What is the difference between the two?  What circumstances would make one more appropriate than the other?  These are some of the questions that we are frequently asked.  To address these questions, let’s take a look at each of these methods.  For these examples, I will be using Adobe® FrameMaker® as my editor.

Conditional Formatting

Conditional tags can be applied to individual characters, words, sentences, or whole paragraphs.  You can then display or hide the tagged text within the document with a few clicks of the mouse.

Before you begin to write your document, make a list of the conditions that you may need to set.    For the purposes of this example, I have identified two conditions: Condition A, and Condition B.  Once these conditions are identified, you can create condition tags.  Some editors allows you to designate text colors that will be displayed once a tag is applied.  These colors are called Conditional Indicators.  You can turn these indicators off globally before you print or export your document.   I chose to use Green for Condition A and Red for Condition B.

As you develop your document, mark content that you would like to manipulate with a conditional tag.  First, select the text, and then apply the predefined conditional tag. 

  

Once your document is complete, you can manipulate it by showing or hiding certain conditions.  In the example below, I have hidden both Condition A and Condition B. 

 

 The next example shows Condition A and hides Condition B.

 

This method of manipulating a single sourced document makes it easy to manage multiple input combinations; however, it does not lend itself well to multiple output levels.

Attribute Filtering

Attribute Filtering provides more options than conditional formatting; however, it is applied at a higher level.  Where conditional text could be applied to a single character, word, or sentence within a paragraph, attributes are applied to the paragraph itself.  If you have to change just one character in a paragraph in order to achieve the desired output, you will need to duplicate the paragraph, make the change, and apply different attributes to each.

To apply attributes, you must be working in a structured document.  As you develop your content, set the appropriate attributes and their values.  For example, you could have an attribute of “Condition” with possible values of “1“and “2.”  Additionally, you could have an attribute of “Level” with possible values of “A “and “B.

  1. Attribute = Condition
    1. Value = 1
    2. Value = 2
  2. Attribute = Level
    1. Value = A
    2. Value = B

Once your attributes are assigned, you can develop filter expressions.  Filter expressions are Boolean expressions that dictate what content is displayed or hidden.  Some possible filters for the above attributes and values are:

1. Common Text Only:

NOT (Condition=”1” OR Condition=”2”) AND NOT (Level=”A” OR Level=”B”)

2. Condition 1 + Level B

NOT (Condition=”2”) AND NOT (Level=”A”)

3.  Condition 2 + Level A

NOT (Condition=”1”) AND NOT (Level=”B”)

4. Level B only

NOT (Condition=”1” OR Condition=”2”) AND NOT (Level=”A”)

As you can see, attribute filtering is a powerful means of controlling various outputs; however, it works best when there is a singular input.

To further illustrate, let’s take a look at two hypothetical clients.

Hypothetical Client A

Client A produces one basic type of heavy industrial equipment; however the machine is customized for each customer.  There are 82 possible features and options, giving them an almost limitless potential for customization.  It is impractical to pre-write individual user manuals and product guides for every potential configuration.  It is ineffecient to create a draft-to-print custom manual and guide for each possibility.

The output will always be either a pdf or a printed document, and will always be delivered to a consistent audience level.

Using conditional text is the correct answer in this case.  The output is always the same level (ie. there is only one audience), it is the input that changes.  Manipulating the document by setting conditions allows you to precisely control the features and options that are included.

Hypothetical Client B

Client B produces a few different industrial machines.  Each machine requires three levels of publications: a Product Operation  Guide, a Preventative Maintenance System, and an Installation Manual.  Each of these manuals will focus on different aspects of the same machine.  Some of the content in each will be common; however, the steps that are required for various processes will vary greatly from one user level to another.

In this instance, the input is constant while the output changes.  Attribute filtering would be appropriate for Client B.  Manipulating the document by filtering attributes allows tight control over the documents that are produced, ensuring that the correct information gets to the correct audience level.

Choose Wisely

Each of these methods requires a different approach to writing your document.  Before you begin to develop your content, ensure that you have selected the best method of managing content.  Choosing correctly makes it easy to produce the desired results.

Tags: , , , , , , ,
Posted By: John Crews | Post a Comment! »

Adobe Frame Maker Training: A Results Oriented Approach

Tuesday, February 16th, 2010 - Posted By: Scott McDonough

We were doing some consulting for a manufacturer that had been tasked with launching a more-or-less new technical publications department. I say “more-or-less new” as the company had always tried to produce and keep up with technical documentation to support their products, but the process was ad hoc at best, and completed by any available warm body with access to a desktop computer, Word and/or an ancient version of Corel Ventura . As the company grew this became problematic, as you can imagine. The manufacturer’s decision was to formalize a group that would be responsible for ensuring that product was always accompanied by relevant documentation.

One lucky staff engineer was appointed manager of the new, albeit non-existant, technical documentation group.  Beyond a fresh set of licenses for the still-uninstalled Adobe Technical Communication Suite software, this manager was not working with very much to start. Of particular interest was training on the use Adobe Frame Maker for the newly-minted technical writers.

The manager was well aware of the prevalent training options. Adobe themselves offer training, and there’s an entire cottage industry of third-parties dedicated to offering  training on just about any piece of software imaginable. Costs vary somewhat based on the location, duration or the supplemental training materials provided, and many focus on providing the trainees with a means to getting their feet wet with Frame Maker. A good functional overview , if you will.

This is all fine and good, and certainly of benefit to many people seeking to learn more about Frame Maker and it’s capabilities. However, for this particular customer, we advised a results-oriented approach.

Why? Not because there’s anything inherently wrong with sending a staff of writers to Frame Maker training; but as consultants we have an obligation to consider our customers’ actual requirements. Not to mention that we’re a service organization and it’s what we do afterall, create clear paths to results for our customers.

Given this customer’s requirements, we determined a course of action that best fit the description of a results-oriented approach to Frame Maker training. I’ve sketched out that approach below; maybe you will find it of use within your own organization.

1.  Create a Frame Maker template. One of the most important and useful things you can do is to create a standardized Framemaker template (or templates) for your documentation. Work from an example of your existing documentation; establish the look, feel and approved writing styles to create a consistent set of components for you and your writers to use when working within Frame Maker. Think of this as the common skeleton for all your manuals. A solid template should contain the following:

  • A graphical representation of the way your documents are laid out on the pages, i.e. pre-defined sections and spacing; what goes where (“frames”)
  • All standard boilerplate information such as your front matter, corporate logo, page header and footer definitions (page number, doc part number, contact info etc.)
  • A library of approved styles to be used within your manuals. Again, working from the styles you’ve used in the past (or created as new), you can pre-define the available selections your writers will need to have access to on a day to day basis. For example, for all of your chapter or section headings, you can create the component within Frame Maker as say, “Section Head”, so when selected, you simply type the text and Frame Maker will automatically apply the correct positioning on the page, space around the text, font, size, and other attributes. The same would apply to warnings, cautions, notes, numbered or bulleted lists, body text, etc. This will ensure consistency across all of your documents.
  • Include instructions for use within the template itself. Not only can you create the tools; you should show examples in use within the template and include instructions on how to use written into the template document itself. This way, any writer can open up the template and immediately see how different styles are to be used, and can keep a copy if they wish as a quick reference as needed.

Template creation is an important first step to ensure that your publications retain the same structure from document to document regardless of who does the writing within your group. Good templates also establish the standard of usability for readers, and should represent your brand in a positive manner.

Note that very few, if any Frame Maker training courses will provide a customized template for you to use, yet this is absolutely key to begin using Frame Maker in a meaningful way and should not be overlooked.

2. Think job-specific training, not just software training. Taking a class on Frame Maker may not meet your groups’ requirements in and of itself; especially if one of the requirements is to get productive quickly. Adobe also offers a self-guided instructional manual with Frame Maker of course, but often times users find it about 50% more than they need to get their job done, and it’s hard to know at a glance what is pertinent information and what is not.

 
Consider how your staff will use Frame Maker day in and day out, then focus on training that addresses these real everyday requirements. As part of your company’s Frame Maker training you should incorporate the following:
  • A Quick Reference Guide for your staff. This should be the “SOP” for anyone present or future who has the role of technical writer at your company. Even as people move on, this remains, to serve as the reference on how your company’s documents are created using Frame Maker. Again, this should be completely specific to the production of your documentation, not a generic guide on the use of Frame Maker that leaves it to your staff to figure out how to apply it to your specific application.
  • Instructor-led training that will ensure your staff get hands-on experience working in your specific template producing your manuals under the guidance of  an experienced Frame Maker user. This way, the tasks learned are 100% 1:1 applicable to the actual jobs your staff will be doing day to day.
Combined, these components will absolutely ensure that your group will quite literally hit the ground running. Focus on creating productive, efficient technical writers, not just a  staff that knows a lot more about Frame Maker overall, but are still unsure of how that applies to their jobs.
 
Cost deserves a mention as well. Good, bad or otherwise, one of the biggest factors in selecting a resource for Frame Maker training is cost.
 

Perhaps harder to quantify on paper for comparison’s sake, but how much is it costing every day that your group is not up to speed producing new documents or working through a back log? What tolerance will there be internally for the time and expense of off-the-shelf software training that does not yield practical and immediate results? Based on the wages and benefits of our staff, how much time would have to spent dealing with inefficiencies before that cost is equal to or greater than the cost of our developing a training program as outlined above? Worth your time to take a look at both.

Basic Frame Maker training will yield an overview-level understanding of the entire range of Frame Maker’s capabilities. Yet upon completion of software training, you will not have a template to work from, will not have had the benefit of practical time working on your specific manuals, and if a person moves on, that training is gone.  Equip your group for the long term; don’t risk stop-gapping the issue with insufficient software training.

 

 

 

Tags: , , , , ,
Posted By: Scott McDonough | Post a Comment! »

Developing a Flexible and Sustainable Training Program

Monday, September 14th, 2009 - Posted By: Scott McDonough

We have had the good fortune to develop many training materials for our clients over the years. Regardless of the training topic, there’s always something especially rewarding about developing training content. I think one of the reasons we enjoy it so much is the fact that multimedia is often involved and the delivery platform can vary from print materials to the Web. Compared to technical documentation that only exists on a shelf somewhere (yes, we still work on those projects too!), training programs often represent an opportunity to be creative while flexing our design and programming muscles at the same time.

Recently, we were talking to a client about transitioning their legacy printed training materials into a more robust program that would be both easier to maintain and reach more of their employees and customers.

Their situation was not at all unusual or uncommon by any means. I’m sure many of us are familiar with a scenario like this one:

-The training curriculum is developed in-house using Microsoft Word or a similar word processing application.
-The curriculum is distributed electonically via e-mail and manually via printing and mailing.
-The curriculum is delivered by multiple instructors, who are responsible for not only the delivery of the training, but for the management of the trainee information and testing results as well. Consequently, there are no real standards behind the delivery of the training and no knowledge retention metrics for the trainees.
-The travel requirements for instructors and customers alike were becoming a greater and greater burden.
-No clear path for remediation. If a trainee can’t keep up with the instructor, oh well, at least he or she attended, right?
-Multiple revisions of the training content exist internally; one or two internal experts might know which is current.
-Internal training rarely keeps pace with the needs of the ever changing organization, and external (customer) training can’t keep up with the speed of product release and revision.

The client was unsure of their direction and was pretty overwhlemed by what seemed like a long, difficult, and expensive path to achieve their goals. Our team evaluated their current situation along with their requirements and came up with the following recommendations.

*Starting at the source of the training content, transition out of Microsoft Word and into an XML-capable authoring program, like Adobe Frame Maker. The cost to obtain a couple of licenses for Frame Maker plus the time to learn how to use it in a structured environment is relatively small compared to the inefficiencies and risk of a poorly managed training program. (Incidentally, this client took us up on our offer to teach their training personnel how to use their new software.) There are of course other good quality and robust XML-capable authoring platforms; the point is simply that the first step should be to ensure you can create content that can be easily reused within other applications and locations. This alone opens up a world of opportunity to improve your curriculum management and delivery processes. Now all of the training content that was once shackled within the stuffy confines of Word can be reused almost anywhere.

*Leverage the now XML-rich content into a Web-based delivery platform. Web-based delivery of curriculum has a number of nice advantages. The curriculum content and method of delivery is always the same (standardization), its available to anyone with access to the web and proper log-in credentials (accessibility) and trainee/student management can be automated. Also, the travel once required to deliver the training can be all but eliminated (reduced cost). What we recommended was to convert the legacy print curriculum into smaller computer based training (CBT) modules. Granted, “custom CBT module” and “inexpensive” typically aren’t used together in the same sentence, but because a large portion of the actual training content now existed (and will continue to exist) in an XML format, the overall development costs for the CBT modules were minimized. Using another Adobe product, Captivate, content generated in Frame Maker can be directly reused within the CBT modules.

*Take full advantage of the CBT environment. Using a good CBT development tool like Captivate or similar, we were able to show our client how to take full advantage of this type of platform. What was once simply text and line drawings, can now be enhanced with Flash animation and digital images. The pace of the curriculum delivery is now dictated by the trainee instead of the instructor. Exams to measure subject matter retention can be built in, with direct paths to remediation built in. If a trainee misses a particular question or answers one incorrectly, the CBT can be programmed to immediately redirect the trainee to review the relevant material and try the answering the question again. Once a CBT is completed, results containing the trainee can be directly e-mailed to any address or addresses, or if there is an learning management system in place, the results can be directly integrated into most any database, allowing trends to be identified and reviewed. Internal training and testing can be turned into customer training by simply removing any portions that are not applicable to the customer side of the training.

*Implement revision control and execute revisions. The clients’ training curriculum is dynamic and must be updated from time to time to reflect product revisions and procedural changes. However, not all changes are equally critical. In order to contain what would otherwise be a continuous stream of updates, we helped the client implement a “major” and “minor” revision control structure. While simplistic, this really helped them get a handle on revision control. “Major” revisions are classified as those revisions that have to do with personnel or customer safety, as well as those things that may cause damage to the product. These major revisions are executed immediately. “Minor” revisions are classified as those revisions that describe a non-critical update in the product or procedures, and do not have an immediate impact on safety. These are collected by the training group and pushed out in a new revision on a regular basis, perhaps every two, four, or six months. In either case, revisions are made at the source document level, and then pushed out via XML to the CBT modules. This way, if there are revisions required to the CBT content beyond the shared XML content, (exam questions or anything unique to the CBT), the updates can be planned for and done all at one time making for a much more controlled and efficient process.

Ultimately, we were able to help our client achieve their goals of a training program that is more easily maintained, better controlled, and far more accessible to both their own personnel as well as their customer base. See what I mean? Training is fun.


View Scott McDonough's profile on LinkedIn

Tags: , , , , , , , ,
Posted By: Scott McDonough | Post a Comment! »