How to Create a DITA Topic Object in FrameMaker

Welcome to my tutorial on How to Create a DITA Topic Object in FrameMaker

FrameMaker (FM) has a very powerful and built-in DITA (Darwin Information Typing Architecture) engine under its hood. Also known as “structured authoring,” this functionality comes with the FrameMaker as a default feature.

When you buy FrameMaker, you do not need to pay extra for “structured authoring (SA).”  To turn on the SA interface, all you need to do is select Edit > Preferences from the main menu to display the Preferences dialog box:

Select Global > General. Then select “Structured FrameMaker” from the Product Interface drop-down menu, close and restart FM11. Now you can create DITA-compliant structured document, thanks to FM11’s built-in DITA engine.

Please note that:

(1) DITA is not the only structured authoring “XML schema” available out there. There are other ways to create structured documents without using the DITA “protocol,” so to speak. There are other “body of rules” that determine which “elements” should be included in such a document and what the relationship between those elements should be. But DITA is arguably the best known structured authoring platform in technical communications. That’s why FrameMaker featured DITA since version 8.

(2) Just because you have selected structured FrameMaker as explained above does not mean that all the documents you’ll create will turn out to be DITA documents. No. You can still create good’old unstructured documents even though FrameMaker11’s GUI will display extra menu item not found in unstructured mode. However, if you set your FM11 to “unstructured,” then you cannot create DITA documents. Thus it’s good practice to always set your FM11 to structured mode since that allows you to create both structured and unstructured documents, as you wish.

Quick reminder: When you create a DITA-compliant “object” you create one of the following types documents (regardless of size and complexity): Map, Bookmap, Topic, Task, Concept, Reference, Glossentry, Glossgroup. In this post we will show you how to create the all-important “topic” object/document in FM11 without going into a detailed explanation of each object. That will be addressed in other posts.

How to Create a DITA Topic in FM

From the main menu, select DITA > New DITA File > New <topic>… to display the default topic document:

As you can see, FM has already inserted place-holders for a number of document elements including:

• (Topic) Title
• (Topic) Short Description
• Author
• Body Text
• Related Links

If all you’d like to have in your topic document are these elements, then you can go ahead, click on the place-holder text and select it, and type in your own content. For example:

The formatting of each element (font family, size, color, indentation, etc.)  is determined by the documents default CSS (Cascading Style Sheet) that is loaded behind the scenes when we created this document. The style sheet can be edited but is not the topic of this post.

But what if you’d like to have additional elements in your topic document, like an unordered or an ordered list, or additional paragraphs of body text etc.?

Before showing how to do that, I’ll ask you to display two panels on the right side of your screen as a matter of good practice:

• Structure View (from the main menu select StructureTools > Structure View)
• Elements Catalog (from the main menu select Element > Element Catalog)

Here is how our workspace looks like with these two important view panels (you may have to right-click these two panels and select “Expand Panels” to achieve the below look) :

If “Variables” or any other tabs are displayed at the bottom of your screen, you can leave them as is or right-click and select “Close Tab Group” to hide them for the time being.

Let’s add a new paragraph right after the existing one.  You can do that in two ways:

METHOD 1: Place the cursor at the end of the first paragraph and then press the ENTER key on your keyboard, just like you would in a “regular” (that is, “unstructured”) document:

As you can see, as soon as we add a new paragraph into the document, a corresponding “p” element is added to the Structure View.

METHOD 2: Place your cursor under the FIRST “p” element in Structure View and then Insert a “p” element from the ELEMENTS list:

Once we click Insert, a second “p” (paragraph)element is inserted into the document with a placeholder text, and we are back to the same situation:

Both methods work equally well because FM11’s EDD (Element Definition Document) allows one paragraph to be inserted after another, whether we do it manually from inside the document or through the Structure View tree-diagram and the Elements panel.

But that may not be always the case.

If for example we want insert an UNORDERED LIST right after the SECOND paragraph, the manual method will not work because the minute we press the ENTER key after the SECOND paragraph,  FM will create a THIRD paragraph element, and not an UNORDERED list. For that, we need to use the Structure View.

Place your cursor after the SECOND “p” element and click to transform it into a small triangle.

Then, from the ELEMENTS panel, select the “Ul” (Unordered List) element and click the Insert button.

Look what happens when we click and insert the “ul” element:

Not only FM inserts a “ul” element but also the associated “li” (List Item) child element and the obligatory “p” child element since without a “p” you cannot enter any text to a list item. And so on.

There is much to be said about this process but we’ll stop here, to continue in yet another blog post.

Our goal was to familiarize you the reader with the basics of creating a “topic” DITA object/document in FM. We hope we’ve achieved that goal.