FrameMaker 10 Basics: Getting started with a DITA Topic Part 1

Most of Adobe's products, such as Photoshop and InDesign, are intuitive and fairly easy to learn. FrameMaker, however, can be a challenge even to the most dedicated XML or Adobe enthusiast. Lynda.com has a fairly good overview of Unstructured FrameMaker but if you plan to start with structured FrameMaker and DITA then it's a good idea to try out the included DITA templates.

Note: Most professionals I know are divided on FrameMaker. Some criticize the software for being unusable, noncompliant to current XML standards, and for being extremely buggy. Others have embraced Adobe's technical writing software. If your company or school is using FrameMaker then it's a good idea to learn the basics of FrameMaker anyway since there's more likely an XML designer working behind the scenes. It is important to know, however, that there are a few excellent commercial alternatives such as Madcap Flare and Oxygen XML Editor. Moreover, if you're a Linux user then you have a wide range of choices, from IDEs to plain text editors such as Bluefish and cross-platform XML Copy Editor.

If you are just getting started with DITA then I recommend a really well written article by Hussein Shafie entitled DITA for the Impatient.

To begin writing a DITA Topic in FrameMaker 10:

1. Click File then New. Select DITA then New<topic>...

2. Input a filename and click Save

3. FrameMaker loads the Structured Authoring workspace and should display the Structure View, Attributes, and Elements panels.

Note: One concept that can be difficult for those familiar with typical WYSIWYG applications is that for FrameMaker you work primarily on the Structure View panel (for XML tags and the outline of the document) and the Document window (for the readable text). For clarity, this tutorial will specify if the step will be done in the Structure View panel or the Document window.

5. On the Document window, select TOPIC TITLE and type your topic. Do not press the Return/Enter key after entering your title. To avoid confusion, avoid using the Return/Enter key when working in the Structured Authoring workspace.

Note: For this tutorial, I'll be using text from an openSUSE Linux article I published in Unsolicited But Offered. The KInfocenter article has been edited to fit this tutorial.

6. We'll now insert a Short Description, an optional part of a Topic as recommended by DITA 1.2 Specifications. If you need a guide, you can download the DITA 1.2 Specifications as a PDF or CHM for Windows users. For the sake of brevity, this tutorial will only focus on using title, shortdesc, body, ordered list, and related links to structure the document.



7. On the Structure View panel, place your mouse pointer under title so an arrow is displayed. Click once for a structure insertion point (a 90 degree rotated triangle) to be displayed.



8. On the Elements panel, click shortdesc and then Insert.

9. On the Document window, a text insertion point is now available. Enter your short description for your Topic.

Note: If you are going to paste text from another source, use the Paste Special option under the Edit menu. Select Text (for plain text) to avoid any markup or encoding issues.



10. On the Structure View panel, place your mouse pointer under shortdesc so an arrow is displayed. Click once to produce a structure insertion point. Select body on the Elements panel and then click Insert.



11. On the document window, type or paste your short description.

12. On the Structure View panel, place your mouse pointer under p and click once to produce a structure insertion point. Select ol (Ordered List) and then Insert.

Note: If you make a mistake and select the wrong Element from the list. Do not click Undo as you would with InDesign or Photoshop. Instead, select the Element from the Structure View panel and right-click. Click Clear.



13. On the document window, type or paste your first list item.

14. To add additional list items to your list, just repeat the process in the Structure View panel but clicking underneath the li element. If you make a mistake or press the Return key or input the text/tag in the wrong place, just right-click on the item in Structure View and click Clear.

Note: Don't worry about adding links, using other elements like bold and figure quite yet. Finish your main text first and you can add additional elements using the Wrap option later.

15. On the Structure View panel, click the - next to ol to collapse the list once you are finished to give you an abbreviated preview of your structure. We will now add the related links element to complete the article.

16. The related links deserve a special section of its own so click under the main hierarchy of topic. Do not click under body or ol in the Structure View panel.

Note: FrameMaker will assist you by not displaying related-links on the Elements panel if you click under ol or body.

Select related-links on the Elements panel and click Insert.



17. To add links, click link on the Elements panel. FrameMaker 10 will display the DITA Link panel.



18. For this tutorial, we'll add a simple External Link. In the DITA Link panel, click External Link.

19. In the DITA External Link window, fill out the Link Target(href): and Link Text: items. Click OK.



20. On the document window, the new external link will be added. To add a description, click under linktext in the Structure View panel and select desc (Description) on the Elements tab. Click Insert.

Note: FrameMaker has a bad habit of persistently displaying the DITA Cross-Reference panel after you add links. Just close the panel and click on the Elements tab and Structure View tab to display them again and continue working.

21. To add more links, repeat the process by adding another link element under related-links.

22. Click File then Save to save your document. By default, FrameMaker 10 saves the document as *.xml but if you plan to use the document as part of a larger DITA-based project, rename the file with the file extension *.dita from File Explorer.



Continued in FrameMaker 10 Basics: Getting started with a DITA Topic Part 2

Comments

  1. Oh my goodness! Amazing article dude! Thank you,
    However I am experiencing difficulties with your RSS.

    I don?t know why I am unable to join it. Is there anybody having similar RSS issues?
    Anybody who knows the solution can you kindly respond?
    Thanks!!

    ReplyDelete

Post a Comment

Popular posts from this blog

Quick Fix: MS Office Click to Run and CPU usage

Notes on UPnP/DLNA media streaming with Windows 10

Vivosmart HR: Setting up Notifications and Music Controls Part 1