FrameMaker is a real DITA editor…a very poor one

Last month, a pair of blog posts dueled over using FrameMaker for authoring XML.

Since the bullets were flying, I thought I would let off some shots of my own. I can’t speak to other XML use cases or schemas, but I do have a comment about using FrameMaker for DITA. Starting in November of 2011, I had to use FrameMaker 10 as a DITA editor for about six weeks until I had time to reconfigure the publishing process for another tool (and pretty up PDF output with mypdf). I’ve had a good deal of experience with writing and producing DITA content with XMetaL, and I agree with the criteria that Mr. Aldous sets out. So I can say that, yes, FrameMaker is a real XML editor.

It’s a really really lousy one.

As Mr. Baker states, “A real XML editor…is not one that presents a DTP interface over an XML schema that is an abstraction of the printed document.” No disagreement here at all. While DITA is (mostly) not an abstraction of a printed document, it does present a DTP interface over the schema. When I was Cheap Barcelona football shirts authoring DITA using FrameMaker, sure enough, I saw a page-like interface. I was tricked into thinking that it was somehow WYSIWYG. It’s most certainly not. Line and page breaks move around on the screen depending if you have tags on or off, and the screen presentation most certainly has no relationship to the output. It also doesn’t give a full document view. So while FrameMaker promises a DTP interface (which I agree would be a bad thing), it doesn’t even deliver on this promise.

In my view, though, there was one really unforgiveable issue with FrameMaker: it allows you to insert elements where they are not allowed by the schema. Sure, it will raise a warning when you try to save a file that violates the schema. Then you can try to fix the issue (if it doesn’t crash first, or if you Cheap Manchester United football shirts don’t need to resort to editing the XML), but this is hardly an example of authors “becom[ing] become productive with minimal training as they are using a familiar interface”, as Mr. Aldous puts it.

I have seen discussions where FrameMaker is said to be a good transitional system for people moving from structured or unstructured FrameMaker to DITA. I completely disagree. DITA is a complete paradigm shift; holding on to a legacy technology might make you feel that the transition is being eased, but the old interface will fool you into thinking that things have changed less than they have. You’re also likely to be frustrated that the DTP nature is an illusion.

If you are making the switch to DITA, then make the switch. I’d suggest evaluating multiple authoring tools; yes, including FrameMaker. But don’t let it fool you by having an interface that you’ve seen before.

Other gripes with FrameMaker

  • It’s unstable. In particular, typing <enter> after a step element causes it to crash. Version 10.0.2 was supposed to fix this issue, but it didn’t for me.
  • You lose undo history after saving a file.
  • Opening a file automatically makes FrameMaker think that the file has changed. If you use a version control system (such as Subversion or git) as I do, this can lead to many “versions” where nothing has changed in the topic.
  • There is no raw XML view–the closest is an option to view  the open file in Notepad. (Because who doesn’t love editing XML in Notepad?)
  • It pollutes the markup. For example, it adds unnecessary (albeit valid) attributes for tables and images. I want layout to be done in the stylesheet, not in the source. Fortunately a little XSLT will clean up this pollution.
  • Output doesn’t really work, although one would think that Adobe would be pretty good at producing PDF at least. I used Leximation’s DITA-FMx plugin, which addresses a number of the problems with FrameMaker. DITA-FMx has a lot of great features, including some I would like cheap football tops to see in other commercial DITA editors. But why should I have to buy another piece of software to fix FrameMaker? No doubt the FrameMaker apologists will discount my experience–but apparently cheap football shirts Scott Prentice has a market for this package so I don’t think I’m alone.
In case you are interested, I’m moving to oXygen. In the past I was happy with using XMetaL and XMLSpy. I find that oXygen works great for both authoring technical content in DITA and working with other cheap football kits types of XML, including developing XSL stylesheets. I’d rather have one tool than two when possible.

16 thoughts on “FrameMaker is a real DITA editor…a very poor one

  1. I said in Twitter that I agreed completely with this article; on second thought, not quite.

    The writer criticizes FM for letting you enter invalid DITA, just flagging the error when you validate. I actually find this a good thing: by making you to debug your DITA code, it forces you to learn DITA better than a more handholding approach would.

    The fact that it flags errors by line number but doesn’t display line numbers anywhere in the interface is an obvious shortcoming, but perhaps we can say it adds a little absurdist humour to the workplace.

    • I suppose then it’s a question of what the purpose of the tool is: is it to facilitate authoring content or to teach you an XML schema? I’d say it’s the former. All the other XML editors I have used prevent you from violating the schema during authoring, not just while saving.

      • Honestly, the first time I used Framemaker/DITA on a project, my main personal aim was to learn DITA, so I didn’t mind having to muck with the validation. The positive thing about being allowed to write invalid code, is that you don’t get it right until you understand it.

        This doesn’t mean, BTW, that I think Framemaker is a good DITA authoring environment, just that this one aspect is not all bad. I prefer oxYgen.

        • “This is easily sovled: if a namespace prefix is declared locally in a doc, it overrides registered namespaces; if not, the prefix must be registered… alternatively, w3c could have claimed all x* namespace prefixes.”But that makes non-registered namespaces second-class citizens… I’m not sure that is a desirable situation.Anyway, yeah I guess I agree with the basic point; XML is not perfect. Then again, for most of the things you sum up, I can see the rationale for why they were done the way they are.Such as the basic syntax of XML; it does force the language and its extensions into a form that is probably not optimal or most user-friendly (e.g. namespace syntax, end tags, the need for shorthands, DTDs). Yet the decision to base XML on SGML has given the language an early boost in popularity, contributing to its success.Or the DOM syntax; dropping text nodes is not possible because markup languages such as XHTML depend on it (e.g. x y would show “xy” instead of “x y” without it). And not-exactly-short property and method names were chosen to minimise conflicts with existing object properties (such as those of ‘DOM 0’).Or why attributes are in the null namespace as I mentioned earlier.Etc. etc.

      • I’ve been using FrameMaker for about 6 years, and each release just gets bteetr and more reliable. I’ve been using version 7 for about a year now, and it has never crashed once, nor has any document become corrupted or unusable. That may sound like faint praise, but after years of using Microsoft Word and having large documents suddenly forget where chapters begin or having numbered lists re-number themselves nonsensically, I SO appreciate FrameMaker’s stability. I’ve made manuals of over 400 pages with FrameMaker with never a problem that wasn’t of my own making. This software is just really SOLID and RELIABLE and great for doing large documents. I’d never go back!

    • Here’s my $.02: some authors need to know DITA well. They need to understand down-the-pipeline repercussions of one data structure over another. In that case, forcing them to debug is one way to teach them DITA. (Another way would be to show the error immediately, as Oxygen and XMetaL do.)

      But other authors don’t need to understand the nitty-gritty details of DITA. Their primary job responsibility is to write content. In this situation, the tool should prevent users from making validation errors to begin with.

      FrameMaker 10 seems to be catering to both groups, but perhaps not serving either one as well as it should. Personally, I use two tools: Oxygen for authoring content, because it hides the complexity of DITA; and XMLSpy for any DITA development tasks, like troubleshooting builds.

      Finally, I just mention that what all these tools seem to largely ignore are constraints. (I know you can implement them with Oxygen and XMetaL, though the latter is clunky. Not sure about FrameMaker.) The first task as an implementor of DITA should be to set up your constraints; there is a great opportunity for authoring tools to enable this through a nice wizard or other friendly UI. With constraints in place, you have fewer elements/attributes to choose from and fewer opportunities to create validation issues.

      • FM is a life saver for long documents. I’ve seen more copurrted Word documents than I care to remember. FM is fast, stable, and versatile. Its weaknesses are typography and colour management.What it offers over Word:Stability, table styles, inline graphic placement options, sideheads, runin paragraph styles, independent and outline numbering systems that always work, graphics library (reference pages), conditional text, variables, complex headers and footers, straddle heads, ability to pull in photoshop and illustrator files directly.What it offers over InDesign or Quark:Numbering, table styles, inline graphic placement options, sideheads, paragraph styles that can straddle columns automatically, variables, equation editor, footnotes, various automated lists.Yes, the keystrokes are left over from its Unix heritage, and there is only one level of undos. There is a learning curve, but for long documents, it has no peer. Ventura is not as stable, and LaTex is too complicated. I wouldn’t recommend it for making a newsletter, but for long and technical documents with numbering, tables, cross-refs, etc. it is a wonderful program.

        • The effort to covrent to semantic markup can be considerable. But rather than ask why should we do this at all? , a more helpful question might be how did our content get to this condition? .Imagine the internal monologue of an author writing an unstructured procedure. Ok, so first I need to get the reader to this screen. I selected Advanced Options ‘ from the System’ menu to get to this Advanced Options’ window. Then I clicked the Logging’ button. Select System > Advanced Options, then click Profiling. Ugh. That reminds me. That new writer used colons between menu items in the last topic I reviewed. I’ve told her that we use the greater than sign, but she keeps slipping into habits from her last company. I wonder how many times she’s done that. We use colons for list introductions, so that won’t be easy to find. Now where was I? Oh, I need to apply formatting to Profiling’ since it’s a button. I’ll probably need to provide an example here. I’ll put that in a new paragraph since last time I included an example the validator thought it was all part of the instructions and got totally lost. Inside the author’s head there was analysis. Identifying a cascade of menu items led to putting a symbol between them. Identifying a button led to formatting the button’s label. Identifying a step example led to putting that information in a separate paragraph. The analysis was encoded into the document, but in an abstract way. What makes the paragraph containing the step example different from a paragraph setting the context for a task? What makes the bolded Profiling’ button different from other bolded text? When usability testing leads to renaming the Profiling’ button to Filtering’, how will we be sure that we’ve changed all the instances of the Profiling’ button? How will we be sure that we haven’t changed other uses of the the word Profiling to Filtering ?This document maintenance task becomes harder because part of the analysis originally done by the author was thrown away through abstraction. At least two bad things happen as a result. 1) Machines can no longer reliably apply logic based on that analysys they can only apply the abstracted formatting. 2) Consequently, maintaining the content requires that the analysis be repeated as authors (and possibly readers who use search) manually sort through search results and mentally filter out those that don’t match the expected result.

  2. My biggest pain point with FrameMaker’s DITA support was their recommended process for creating a table of contents in your PDF output:

    1. Convert the DITA map to a FM book.
    2. Use FrameMaker’s TOC page type.
    3. Lather, rinse, repeat if you happen to make ANY changes to the content from this point forward.

    Maybe I was just spoiled by the DITA OT automatically generating a table of contents for me in my last job. I KNOW I was spoiled by having people like bcolborn and paqman creating stylesheets and the like, so in my first purchasing decision as the sole technical writer at my current job, I mistakenly assumed “hey…if anyone knows how to create good-looking PDFs, it should be Adobe…”

    DITA-FMx fixed the TOC issue, plus a few others. But in retrospect, purchasing FrameMaker was really just a cheap way to get the other items in the Adobe Tech Comm Suite.

  3. One could consider the fact that it allows you to insert elements where they are not allowed by the schema as an advantage – it gives a writer the opportunity to build his content even when it’s not yet valid XML. That said, even Oxygen will allow invalid markup when working. Try to paste some markup in aplace where it’s not valid: Oxygen will ask you to make it valid or paste anyway and thus creating invalid markup.

    I find the clear visualisation of invalid markup in FrameMaker exremely helpfull when converting to XML or when editing legacy content.

    I wouldn’t position FrameMaker as an XML editor (yet). I’d rather concern it to be a content editor that can handle XML (DITA) very well, because, indeed, it’s not possible (yet) to directly edit the XML code in FM.

    For my clients, mostly technical writers wthuit any knowledge of XML, FrameMaker is in most cases the best choice and the’re all aware of the fact that the WYSIWYG interface is just one option.

  4. I wholeheartedly agree with Wim’s evaluation: “I wouldn’t position FrameMaker as an XML editor (yet). I’d rather concern it to be a content editor that can handle XML (DITA) very well….” FrameMaker was never designed to be an XML editor. It was designed to be, and is, the best desktop publishing package out there. Faced with the need to accommodate the rising standard of XML in tech com, FrameMaker grafted XML onto its existing functionality…using conditional text to handle attribute filtering, text insets to handle conrefs, and so forth. It’s not a bad fit…but it’s not great. It’s sort of like the guy on the sports desk you keep looking at trying to figure out what’s not right about his suit. Some of the issues are not flaws with Frame…for example, Frame’s Table Editor contains a lot of options for which there simply are no equivalent elements or attributes in most XML doc standards, so some table customization might be lost during a round-trip. Some of the issues are definitely flaws with Frame. My pet peeve (and this is as of Frame 9; I haven’t used Frame 10) is that Frame does not generate @height and @width values for DITA elements. All well and good if you stay in the Frame world, but if you want to publish those XML files using the DITA Open Toolkit, you get error messages and unscaled images. To my thinking, if Frame-generated XML throws error messages that XML created in a dedicated XML editor does not throw, then it is not completely standards-compliant. Frame is not. It just isn’t. FrameMaker does itself a disservice by persistently proclaiming that it’s as good an XML editor as Oxygen or XMetaL or any other dedicated XML editor. There would be no shame in simply saying that it provides good XML functionality for writers who want to enjoy the benefits of XML while still working in a familiar Frame environment. I move my writers from unstructured Frame to Frame DITA (because the conversion is so easy with a conversion table) and then to Oxygen. I do believe it helps them make the transition. For that, Frame is invaluable. But I would never want to go forward in DITA or any other flavor of XML with only Frame as my editor.

    • I couldn’t agree with you more on this point, Glenn. It’s one of the bigegst hurdles to get past with authors new to DITA. It’s tempting to say, given their template (especially if they’re authoring in a GUI editor like Frame) to tell them, You have to wrap it in this element to get it to look the way you want. That approach works, but it doesn’t leave them with the necessary degree of distinction between content and presentation. I try to describe to them a future scenario in which, for example, they might want to produce a quick reference guide with just the action part of the step and not any of the additional information. When I explain that having the action in and everything else in or or whatever will give them that flexibility, a light begins to glimmer. However with respect to your example of structuring a step, just this morning I was puzzling over the new 1.2 element . It seems to me that this element was designed to allow authors to do exactly what you are trying to discourage pour everything into one element and make no semantic distinction between the parts of the step. Thoughts on that?

  5. FrameMaker is indeed a really good DTP package. If I didn’t have the option to use DITA, I’d most certainly choose FrameMaker for writing documentation and courseware. However, it’s very apparent that the DITA capabilities were added after it was a mature DTP system. Can a package really be expected to handle unstructured information, structured information according to a proprietary scheme, and several flavors of XML including DITA? I don’t think those are reasonable requirements, and at least one of the three is not going to fit very well.

    • If all word processing/desktop puibhsling software worked this well, the world of writing would be a better place. It’s not perfect, but it is as close as any piece of software I’ve worked with in the past 23 years of doing word processing and desktop puibhsling.With tremendous power and rock solid performance, FrameMaker 7.0 does everything it claims to do. The user delineates what it needs to do and FrameMaker does it. This is such a remarkable improvement from MS Word that our tech writing department has a whole new upbeat, can-do attitude that everyone who works with us has noticed. Need for your document to have complex numbering? FrameMaker does it with ease, grace, and accuracy. We got four days of in-house training and have sailed forward with grins on our faces.This is excellent software, worth every penny we paid for it and the training. If you’re tired of fighting Word templates and numbering problems, if you just want your documents to behave, if you’re tired of Word helping you behind the scenes, FrameMaker can change your desktop puibhsling world from hell to heaven.If you just need to do simple documents and brochures, get WordPerfect. If you need the power to produce documents more complicated and complex than that, get FrameMaker.

  6. I was curious about your thoughts regarding FrameMaker documents and source control. (I know it’s a little off the DITA topic, but I’m a little desperate for knowledge on this topic.) Our company is moving to GIT for the developers, but the technical documentation shared the same source control so we will have to move to GIT as well. While “side by side” comparisons and merges were never something we needed, we do need the ability to lock out other users when a document is being edited, and we do need to preserve the integrity of the documents in some kind of “version tree” with a retreat (or undo) path. Since it looked like you might use GIT for your technical documentation, do you have any thoughts on how will it might work with FrameMaker docs? Thanks!

    • Right now I am using git as my topic repository. Previously I used Subversion for about 2 years with a team of 15 writers until we could get a CMS in place. First of all, give up on the notion of locking. Locking files has fallen out of favor in the version control community. Git instead uses the concepts of branching and merging, which I am still struggling with. Being able to go back in time is, however, the strength of git. Once you’ve pushed something to the central repository, it’s all but impossible to lose the history. I’d question keeping the docs in the same repo as the source code. While the engineers at my company use git, we have a separate documentation repo.

      It sounds like you are talking about binary FrameMaker files rather than topics. At this point I have to put on my topic-based zealot robe and say that managing large and opaque files is your real problem. In FrameMaker (at least with versions I’ve worked with in the past), every time you open the file it changes. Since it’s a binary file, you’ll never be able to tell what changed except with whatever tools Adobe chooses to give you. You can definitely use git to track history, but that’s about all you’re going to get until you move to smaller text (i.e., XML) files.

Leave a Reply

Your email address will not be published. Required fields are marked *