Posts Tagged ‘single sourcing’

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.

The Disclaimer You’ll Never Find on Content Management Software

Wednesday, March 17th, 2010 - Posted By: Scott McDonough

The user shall determine the suitability of the product for his or her intended use and shall assume all risk and liability and connection therewith.”

Product disclaimers are everywhere. Presumably crafted by very smart people wearing suits, who know much better than the rest of us, these little nuggets of wisdom caution us against all sorts of things. Tossing an aerosol can into an open flame for instance, or using hot sauce to rinse out our contact lenses. Essentially, they remind us of what a product isn’t intended for, and what bad things might happen if we don’t pay heed.

However, you’ll find no such disclaimer on a piece of content management software…but there should be, and I’ll explain why.

In our line of work, we talk to mid-market manufacturers on a daily basis. When discussing product support documentation, a remark that we hear all too frequently goes something like this:

“Well, we bought this popular content management system/authoring tool a few years back, but we don’t really like it/use it/are getting away from it.”

Time and time again, we hear the same story. These mid-market manufacturers, by all accounts successful and staffed with intelligent people, decided to move into managed content using a software application, and then at one point, stopped. Why is this?

Was the application faulty or flawed? Did the software company makes dubious claims that simply weren’t true?

In reality, no, neither. Assuming the mid-market manufacturer did a modicum of homework and purchased an application from a reputable software vendor, the application was likely perfectly functional.

The problem is the disclaimer, or more precisely, the lack thereof. It’s what the software can’t do that’s the real issue.

Were I to write a disclaimer for a content management software application, it would have to at a minimum include the following:

The use of this product implies no remedy nor correction of the following issues, included but not limited to:

  • Continued, excessive use of your engineering team’s time spent developing and reviewing product support documentation may result (Product support content will not research, review, and edit itself)
  • May require considerable and ongoing dedicated training resources to ensure proper implementation and maintain consistent use over time
  • It is the responsibility of the user to both identify and structure legacy content for re-use; the software only allows for the potential of this functionality
  • It is the responsibility of the user to establish and maintain an internal process that supports the flow of information into and out of the software
  • The software vendor makes no claim regarding the quality or usability of the content managed within.

Your individual results may vary.”

Content management software companies have done an excellent job making sure they have exposure; it is their job to exist in the spaces where people that have the challenge of developing and maintaining content live.

However, in doing so the line between content development and content management has been blurred and this especially true in the mid-market. It’s one thing to have the ability to single source and manage content, quite another to improve the way it is developed, integrated into internal workflow processes, and then maintain over time.

So after you’ve read all the website materials, sat through the webinar, and heard everything there is to hear about what the software can do, make sure to stop for a minute and consider how’ll you address what it can’t do, too.

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.

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