add a new topic to a dita map in xmetal...

Lesson 1: New Topic Training

Add a New Topic to a DITA Map in XMetaL

OVERVIEW

We use XMetaL Author (software program) to edit and write the content for technical documentation.

Content written in XMetaL is organized using Darwin Information Typing Architecture (DITA).

A DITA map is made up of topics (and sometimes additional DITA maps).

A topic contains the smallest chunk of content that you may re-use in another document.

Here is a sample of a DITA map with topics.

Think of each topic as a chapter in a book. The DITA map is the whole book, and the topics (or additional DITA maps) within it are like chapters, dividing the content into relevant sections.

Each topic is defined by a topic type.

P a g e | 1


Designating the appropriate topic type helps to structure the content within each topic.

The types of topics that JCI technical writers use are:

• Generic Topic: Use a generic topic for the first topic in a map. It contains publication-specific information only.

• Task: Use a task topic if your content has numbered (ordered) steps in it. • Reference: Use a reference topic if your content has tables or bulleted

(non-numbered) lists in it.

• Concept: Use a concept topic when content does not fit into any other category.

Organizing content in topics, allows sections of information to be shared, or re-used, in a different document when needed.

For example, the Advanced Graphics Application Product Bulletin DITA map contains the following topics:

A writer can create a new DITA map and simply re-use a relevant topic instead of re-writing the content.

In the following image, multiple topics are shared between the two maps. The new DITA map (Installation Instructions) shares or re-uses topics from the Original (source) DITA map (Product Bulletin), populating the new document with identical content.

P a g e | 2


Instead of updating the same information within 2 documents, we can update the original (source) topic, and know the content update is reflected in every document using the shared topic. Additionally using one topic means there won’t be discrepancies between duplicated content. Sharing topic content can cut out hours of updating information and avoid content inconsistencies.

Now that you have background information in DITA maps and topics, you will open and edit a DITA map in XMetaL.

TRAINING

Introduction

This training exercise will help you create a new topic and add it to an existing DITA map. After adding the topic, you will generate a PDF file to see how a DITA map formats information in a final document.

Process

1. Move this Word document to the far left side of your screen, and then drag the right side of the pane in, until it is 5” wide.

P a g e | 3


2. Drag the bottom of the Word document pane to the bottom edge of your computer screen.

3. Open the file folder labeled XMetaL Topic Training on your desktop.

4. Right click on the file ending in .ditamap, and then select Edit in XMetaL. When the XMetaL program opens, move the XMetaL window to the right of the Word document.

Note: After following steps 1-4, your screen should look similar to the following image. This setup allows you to read directions (left) then implement them in XMetaL (right).

P a g e | 4


5. Click File > New on the XMetaL menu.

6. Choose the DITA Topic tab in the New selector window,

7. Select Task, and then click OK.

P a g e | 5


8. Type This is a new task topic between the title tags. You are creating a name for your new topic. You’ll see this name populate in the DITA map later.

9. Type This is Step One of an ordered list between the cmd tags. You are creating content for the new top that you created.

10. On the XMetaL menu, click File > Save to save your new topic.

11. In the Save As window, browse to your desktop, double click the XMetaL Topic Training folder, and then double click the 12011525 folder. Note: You can save topics to any drive location, but it’s smart to keep the topic file with other documents from the same project.

P a g e | 6


12. Type AGA_New_Task_Topic in File Name, and select XML Documents (*xml) for Save as type, then click Save.

Note: JCI has naming conventions for maps, topics, and images that must be followed before for consistency. See Naming Convention Guidelines on Sharepoint for more information.

13. Locate the Resource Manager menu in XMetaL.

P a g e | 7


14. Click Insert > Topic Reference in the Resource Manager menu.

15. Click Browse in the Insert Topic Reference window.

P a g e | 8


16. Browse to Desktop/XMetaL Topic Training/12011525 in the Select Topic window, and then select AGA_New_Topic.xml.

17. Click Open. Note: The Insert Topic Reference window shows your selected topic in the Href field.

P a g e | 9


18. Enter task, and then click OK in the Type field. The new topic is now visible in the DITA map.

19. Click File > Save Map on the Resource Manager menu. This action saves the inserted topic to the DITA map.

P a g e | 10


20. Select This is a new task topic by clicking it once, then click the down arrow on the Resource Manager menu to move the topic below Advanced Graphics Application Overview.

21. Expand the Advanced Graphics Application Overview topic by clicking the + next to the topic. The topic will expand to show sub topics.

P a g e | 11


22. Select This is a new task topic by clicking it once. Click the right arrow in the Resource Manager menu to move This is a new task topic below the last sub topic in Advanced Graphics Application Overview.

Note: You can move a new topic to any location on the DITA map using these arrows. The topic order in your DITA map determines the topic order of your final document.

23. Click File > Save Map on the Resource Manager menu.

P a g e | 12


24. On the Resource Manager menu, click File > Generate Output for DITA Map.

25. When the Generate Output for DITA Map window appears, verify that the Save output as field contains the file path to the XMetaL Topic Training file on your desktop (or browse to that location).

26. Click OK to see the XMetaL Author Enterprise window generating the output.

27. Click Open File when you see the Output successfully created window. A PDF document generated from the DITA map information will appear.

P a g e | 13


28. Click on Advanced Graphics Application Overview in the table of contents (TOC). Observe the topic’s font compared to the subtopics listed below it.

29. Scroll to the bottom of page three and locate This is a new task topic. The topic title is bold and italicized, indicating that it is a sub-topic. Because the new topic was moved below the Advanced Graphics Application Overview topic and indented once, it was moved to the level of a sub-topic in the final document.

ACCOMPLISHED:

• You created a new task topic and added it to an existing DITA map in XMetaL.

• You moved the topic to a new location within the map, which changed the topic location and format in the final document.

• You generated a PDF file to see how the new topic was formatted in the final document.

P a g e | 14