FrameMaker – Structured or Unstructured?

If you’re a technical author or in a related role, whilst you may not be working in a structured environment, you’ll certainly have heard about structured documentation and XML and possibly structured FrameMaker.

In this blog, Steven Smith explores these technologies, looking at the key factors you should consider if you’re considering implementing a structured authoring environment, and the benefits you might achieve.

Background

Whilst structured documentation can be tracked back to the early 1950s, it’s mainstream adoption didn’t begin to take-off until  the late nineties when the World Wide Web Consortium (W3C) finalised their XML Recommendation.

Since then, we have seen a steady increase in the number of tools and technologies for working with XML and structured documentation. Whilst all of the tools have their own unique qualities, they all follow the same standard approach, which involves using and XML transformation language to transform XML content to the required output formats, such as hard copy, PDF, online, etc.

The adoption of a structured approach is widespread in industries where consistency and standardisation are of particular importance, such as aerospace, defence and pharmaceuticals.

Should my organisation adopt a structured approach?

Before you off on a structured path, you need to be certain that it’s the right approach for your organisation. It isn’t for everyone.

A potentially significant investment (in time and money) is required to set up a structured authoring environment, and it doesn’t work for everyone. In the early noughties, there was a rush to adopt such a system, and I recollect a conversation I had with an XML Documentation Consultant who said he was doing more work helping companies revert to an unstructured system to get them out of a mess they’d got into, than he was implementing new structured systems. Companies were ‘taking the structured leap’ because it was ‘the thing to do’, but it didn’t always work out well.

The key is to make sure it’s the right approach for you before taking the plunge. You should ask whether you:

• Re-use the same ‘chunks’ of content in different publications?
• Have multiple technical authors and other contributors authoring content?
• Provide the same information in different output formats, e.g. hard copy, PDF, and for viewing on the Web and mobile devices?
• Personalise your documentation for different clients, audiences, etc.?
• Localise your content, i.e. provide it different languages?
• Need to comply with existing standards such as DITA, S1000D or DocBook.

There are certainly other factors you should consider too, but these are the key ones.

A structured approach supports all of these requirements. So, whilst you don’t necessarily need to answer “Yes” to all of these questions, the more you do the stronger the argument should be for implementing a structured approach.

The benefits of structure and XML

The key benefits a structured approach offers are…

• You can publish to multiple platforms, automatically and quickly. From the same source content, you can produce hard copy, PDF, and material for viewing on the Web and mobile devices. You can set up a single build process that publishes multiple formats at once.
• Consistency and flexibility. A structured approach enforces consistent structure and content within and across the documentation you publish.
• Your authors can get back to what they do best – creating quality content. An approach whereby an author determines content and formatting as the write can be extremely inefficient. With a structured approach, the author is only concerned about writing good content, not making formatting decisions. After all, whilst writing, the may not even know what format(s) the content is going to be published to.
• You can implement a content management system, providing efficiency improvements as well as the ability to manage and track the development and use of information assets.
• You can personalise content for each client.
• You can reuse your content. Chunking and content re-use lowers costs and improves quality offers significant improvements in efficiency and quality. Write some content once, use it time and again

Structured FrameMaker

Now, let’s take a look at Adobe FrameMaker, the authoring tool of choice for many organisations in a structured environment. FrameMaker is used by more people worldwide than any other structured authoring tool.

FrameMaker operates in two modes: unstructured and structured. When you first launch the application, you’re asked which mode you want to work in. FrameMaker remembers this setting, though you subsequently change it in FrameMaker’s Preferences.

In unstructured mode, FrameMaker provides a conventional DTP solution. In structured mode, it provides a fully-featured tool for authoring, editing and publishing complex documents, in multiple formats such as hard copy, and online to smart phones and tablets, in multiple languages.

The structured FrameMaker interface is a superset of the FrameMaker interface. If you work with both structured and unstructured FrameMaker documents, you can do all of your work in structured FrameMaker. There is no need to toggle back and forth between the two interfaces.

Benefits of FrameMaker for your structured authoring

• Familiar interface. If you’ve used FrameMaker in standard mode, much of the structured FrameMaker interface is the same. Many of the features, tools, menus and commands, are virtually identical between the two modes.
• FrameMaker comes with ready-made templates that illustrate the extra value structure gives you.
• No XML coding is required. You create XML content working in a familiar authoring environment.
• FrameMaker provides a guided editing interface to support the creation of valid structured and/or XML documents. Pull-down lists of allowable options and items reduce the scope for errors.
• FrameMaker is an established, mainstream authoring tool. It was first developed over 30 years ago, it is used by many thousands of technical authors around the world and is developed by Adobe.

Elements, not paragraphs

As a technical author, you’ll be familiar with paragraph and character formats available in pretty much all DTP applications and word processors, such as Microsoft Word. When authoring in structured FrameMaker you adopt a similar but different approach, but instead of applying paragraph formats or styles, you select elements.

An element is a label for a chunk of content, which may be a paragraph, section, table, inline element, cross-references, and so on. FrameMaker helps you here by just offering elements relevant to the current cursor position.

Elements in a structured FrameMaker document are held in a hierarchy. Many of the element chunks of content are nested within other chunks. For example, a section is likely to contain a section title followed by paragraphs, tables, graphics, lists, and any other content chunks that comprise the section.

Elements may have one or more attributes, which allow authors to associate additional information with elements. The elements and attributes provide metadata – additional information about the document, which is generally not included in the printed rendition. This information can be invaluable for processing documents for other output devices or for managing documents via content management systems.

The element structure of a document and the formatting requirements for each element are defined by an Element Definition Document (EDD).

Conclusion

A structured authoring environment can bring substantial benefits to many organisations who produce content, but it’s necessarily right for all.

Although significant investment and resources are required for its implementation, the ROI and competitive advantages you achieve can be substantial.

Structured FrameMaker provides an ideal authoring tool for technical authors producing structured content. Its guided editing and validating capabilities assists technical authors, helping them work productively.

If you’re thinking about implementing a structured environment, I hope this blog has been useful, and has given some food for thought.

If you’re already working in a structured environment, I’d like to hear your views. Does it offer the benefits you’d expect? If you switched from unstructured to structured recently, was it worth it?

Armada offers FrameMaker training to users at all levels, working in both an unstructured and a structured environment.

For information about our unstructured courses, FrameMaker see Introduction to FrameMaker and Advanced FrameMaker.

For our structured FrameMaker courses, see Authoring structured FrameMaker documents and Creating EDDs.