Posts Tagged ‘content management’

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! »

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.

Tags: , , , , ,
Posted By: Scott McDonough | 4 Comments »

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! »

Response to an Outsourcing Question Posted on LinkedIn’s Documentation Managers Group

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

Recently, someone from a language translation services provider posted a good question in LinkedIn’s Documentation Managers group. As a language services provider, this person’s company is considering the addition of technical writing to their service offerings. The questions were “why do companies outsource technical writing, how frequently and to what extent?”

These are great questions, and I thought I’d re-post my thoughts here:

-The reasons why our clients choose to outsource technical writing are as varied as the companies themselves. In better economic times, it was often because thier internal resources simply did not have the capacity to meet the requirements. More recently, as internal staff levels have tapered off, we are seeing requests for assistance because the in-house resources that once were simply do not exist any longer.

Also, as [another commentor] pointed out, “technical writer” is a catch-all job title. All of our staff here would be more appropriately described as “content developers” as they have experience not only developing content for, say, product documentation but training curriculum and content for web applications as well. So there sometimes exists a disparity between what a potential customer thinks they need versus what they should be looking for. This subtle issue is one you should be aware of and one we deal with everyday. You may advertise that you are offering “technical writing” services, but your target customer may not equate their particular content development needs with technical writing necessarily because their subject matter happens to be training currciculum.

Some clients simply need an existing document edited to reflect some recent updates. Sometimes a file format conversion is required. Sometimes a person is needed on site to work with product teams to develop and deliver content. Sometimes clients hand over entire product documentation projects to be managed either on-site or remotely start to finish. Again, the reasons for and extent of outsourcing varies greatly.

-It has been our experience that larger companies having strong internal technical writing departments or resources, are often resistant to outsourcing, which makes sense and is to no one’s surprise. However, even these groups will often be receptive to learning more about how to manage their content more effectively. They may not want any help developing the content, but chances are they are drowning in a sea of it and may even be feeling pressure from the KM/ECM folks in their organization to do something about it. In this case, outsourcing the writing of their content probably isn’t going to be very attractive, but the services of a company or experienced technical writer may in fact be. Technical writers experienced with extensible content structure and delivery can still be a viable outsource option.

-A question that comes up frequently when discussing the outsourcing of technical writing is validation and verification of quality. This is especially relevant since the rise of lost-cost outsourcing across the globe. A low per-piece or per-hour rate can sound incredibly attractive to those considering outsourcing, but it must be evaluated to include the additional expenses of the contracting company’s project management and validation/verification time. The reality is that it is just not that simple as outsourcing to take advantage of a favorable exchange rate, there are real additional costs that have to be considered.

-More and more, and back to [another commentor's] point, it is simply not enough to offer pure content development work. While a valuable skill in and of itself, technical writers have found themselves having to respond to the needs of organizations that are shifting the focus to the management of their content. We have seen, over the last few years, more and more clients looking to us for assistance with the structure and management of their content, not just the development of the content. It seems it’s simply not enough to be able to develop content, it pays to know a thing or two about content management as well.

-Your position as a language services provider is probably a good one. We currently partner with a couple of similar service providers and those relationships have proven to be worthwhile.

For the complete discussion, here’s the link. (Though you may have to register for the group if you have not already.)

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! »