Interview with Jang F.M. Graat

Recently DITAWriter.com got in touch with Jang F.M. Graat to talk with him about his thoughts on DITA, the role of FrameMaker and whether DITA is too complicated for its own good. He runs Jang Communication which is based in Amsterdam, Netherlands. Jang F.M. Graat holds Masters Degrees in Psychology and Philosophy and has worked in the high-tech computer business as a technical writer, trainer and consultant. In recent years he has helped a number of small and medium-sized machinery companies to improve their documentation both in quality and cost-effectiveness. Jang became an active member OASIS two years ago, where he is involved in the DITA TC and the DITA Adoption TC. He is currently co-chairing the Machine Industry SC.

DITAWriter: Could you tell me your professional background and how you came to know about DITA?

Jang: After studying Physics for two-and-a-half years, Psychology for seven years and Philosophy for three, it was time for me to find a paying job. Through sheer luck and good fortune, plus a good dose of self-confidence, I landed in the international high-tech computer business. I began working in a small startup company specializing in parallel processing at a time when this was really new. So after learning everything I needed to know about computing – from soldering chips on PCBs to writing programs in assembly language, writing quotations and project proposals, then selling the final product at trade shows – I helped create a worldwide distribution network for our parallel C compiler aimed at parallel networks. After six years of working in this field for two different companies, I was asked to train on it in Singapore and then in Budapest. Another company then hired me to write their electronics product manual and that is when I started my own one-person company, 16 years ago. Most of my work involved writing manuals and presenting products plus delivering product-related training courses around the world for my clients. Once I had written the product manual, I could also deliver the training.

I first became actively involved in the Netherlands chapter of the Society for Technical Communications (STC), then later in the TransAlpine Chapter. This is where I first heard about DITA, when we invited Michael Priestley to speak at one of our conferences in Berlin. In the same period, JoAnn Hackos held her first DITA Europe event in Brussels. I didn’t get to go to that conference but I followed DITA from a safe distance and really got involved in it after going to the DITA Europe 2008 conference in Munich. I have delivered presentations at DITA Europe 2009 and 2010, at CMS/DITA NA 2010 and at NLDITA 2010.

DITAWriter: What types of firms are your typical clients? And why do you find they want to “do DITA”?

Jang: Most of my current clients are small and medium-sized machinery companies. I am finding that they do not want to do DITA, as it reeks of software technology and geeks, but this is a world which considers software a necessary evil and something they only deal with via a special ICT department. Whenever I mention the acronym “DITA” or even “XML” to these clients, they tend to want to hide under their desks and wait until I am gone. I have to explain DITA in non-geek terms so they open their minds and discover that the thought-processes behind DITA are the same as they have been using in their engineering departments for decades and so is not scary at all.

In most machinery companies, documentation is something that is handled by the dumbest engineer on the team, who does not know enough about engineering to create models. They figure everyone has learned to write in elementary school, so why not have the receptionist write the manuals in between the calls?

DITAWriter: I really hope receptionists are not writing the manuals for their firm’s medical devices or heavy machinery! Given what you say though, why would firms be interested in moving to DITA then? I mean, why would they bother giving their manual-writing receptionist any tool other than Microsoft Word?

Jang: In the (true) case of the receptionist writing the manual in between calls: no, that company will not bother about anything to do with documentation technology, as they could not care less about the quality of their documentation. Not that a receptionist would not be able to write a manual, but clearly that task is not taken too seriously by the company.

Firms are not interested in moving to DITA unless they see that their documentation costs will go down dramatically when they do. But this is not the case with all of the companies I have worked with. Some companies are fine with their old copy-paste method of reusing content in Microsoft Word. They might even process the content into a help file, but companies that develop a range of products that are based on a standard set of modules with individual adaptations do think about reuse in order to get their documentation in shape. Depending on the business domain, documentation can be more or less important. With certain machinery domains, the documentation must comply with very strict regulations (e.g. certain warnings need very specific wording). In such highly regulated areas, an update can become very costly if you have to copy-paste the changes throughout the entire set of current documents. Note that each document will have to be reviewed individually in this setup, too. If you can use a defined method for reusing a single instance of a warning, this not only reduces editing costs but also the reviewing and translation processes.

Apart from these obvious reuse cases, there is hardly a machinery company that does not use a DITA-like strategy in their engineering department. 3D CAD models are not copied when the assembly is reused in another machine: they are linked into another design much in the same way as DITA links content into another publication. When a change is made to the module, this change will automatically propagate to all machine models that incorporate the same module. Reusing modules as much as possible is absolutely vital and perfectly natural to machinery businesses. So “why are they not doing the same thing for their documentation?” is the next question. My answer for them is simple: DITA is not really anything new; it is merely copying their usual methods from the engineering department to the domain of documentation. It’s taken a couple of decades, but the tech writing industry has finally become as clever as 3D CAD designers have been for a long time.

DITAWriter: A discussion point that came up at the conclusion of the Vienna CIDM conference was that maybe DITA is getting too complicated. Any thoughts on that?

Jang: DITA is not just maybe getting too complicated, it is too complicated. Not just the number of elements, but the naming of some of these elements and the incredible amount of attributes associated with every element. It is more than would be useful, and this is why I feel that DITA constraints are going to save DITA’s future and a lot of tech writers their professional lives. If I had a documentation department to manage, I would immediately enforce constraints to rule out all those unnecessary elements that have been added simply because some tech writers on the DITA TC were too lazy to really think their concepts through. Horrible concepts like conref range or conref push should have never made it into the standard. An element for “long quote” is not necessary if there is already an element for “quote”. Elements like “b”, “i”, “tt” do not belong in a semantic system. If a table element for specific tabular information is defined, this should have been handled by attributes, not by multiplying all the elements in a table for every type of table people come up with (row, strow, relrow, chrow, topicSubjectRow). Where is the real need for an element “noconds”, “nosafety”, “nosupply”, “nosupequi”, “nospares” if a generic “none” element would have done for all these specific cases? And why not have intelligible names for all elements instead of a mix of acronyms for some (like “q”, “dl”, “dt”) and descriptive labels (like “glossAlternateFor”) for others? The existing standard is pretty messy if you ask me, and this makes the complexity worse for tech writers who need to learn a whole new jargon that is definitely not self-explanatory.

DITAWriter: Any specific thoughts on what good or bad in the DITA 1.2 specification? Any thoughts on what should be in the next spec?

Jang: Bad points: see the answer to your previous question. Of course the introduction of a strict vs. a generic task gives a small problem with backwards compatibility. Other than this, I do not see specific bad things in DITA 1.2 that were not already bad in previous releases of the standard. Except maybe the enormous delay in getting the standard approved, due to bureau-crazy at OASIS.

Good points: the task model is improved; the hazard statement is in line with ANSI Z535, the machinery task makes DITA viable for the machinery industry and most of all the constraints mechanism. Creating constraints is much easier than creating specializations and at the same time it avoids breaking compatibility with others that use the same DITA standard (but less constrained versions). Also it does not require defining transformations for specialized elements, and this does make a huge change in the amount of techie work involved. Now all we need are tools that make creating constraints easy, like the drag-and-drop visual editor I was mentioning during my last talk in Vienna. There are a couple of visual tools that do part of the work that I would like to see in a new tool, but there is no single tool yet that handles all aspects. Most of all, I would love to see DITA become un-technical and un-geekish. This is beyond the scope of the DITA group at OASIS, as it involves creating simple tools, and those tools will be commercial. One of the candidates that may well become an important player on the DITA market for un-geekish writers is Adobe FrameMaker. While frowned upon by many software-savvy writers in techie companies, it is the first mainstream tool to deliver full DITA 1.2 support, which is a remarkable feat given the number of elements and features that were added to DITA. I still need to test how good the support for DITA 1.2 really is, but so far I have no reasons to doubt that it is pretty good. The only area that I still find problematic is how it handles DITA at the map level.

DITAWriter: Speaking as a “tech savvy writer in a techie company”, one of the reasons for turning away from FrameMaker (which I remember using in one of its original incarnations on a Unix system back in the mid-90s) is that for years the improvements that were made to it shortly after the release of version 8 were laughable. For a long time it seemed like minimal updates was the most we could expect. It was a real surprise to me when they delivered a completely revamped program that was capable of working with DITA. For many though (including myself) it was “too little, too late”. Today it seems like a good solution for small writing teams, but without any back-end content management system it seems to me that it’s abilities to effectively re-use content will never be optimal. But I keep hearing some surprising success stories about how it is being used as an effective DITA editor and publishing solution. What has been your experience?

Jang: When FrameMaker 8 was released, the general feeling was that the product was at its end of life, as Adobe was positioning InDesign as their new flagship for anything to do with DTP. FrameMaker 8 was the first version not supported on the Mac anymore, which was a slap in the face to Mac users, given the fact that a version running on Sun Solaris was being continued. How strange can it get? One of the clients using FrameMaker on Sun Solaris happened to be Boeing, and they must have had some influence on the marketing decisions at Adobe. Marketing strategists at Adobe must have imagined that their Mac-based DTP clients would be over-the-moon for trading InDesign for FrameMaker. But InDesign is not designed for long documents with lots of cross-references and other nuts and bolts, the kinds of thing we need in technical documentation. As for tech writers and marketing staff doing DTP, there are not many companies where these people work together in perfect peace and harmony…

Things changed when Adobe acquired Macromedia, which in turn had acquired Blue Sky Software, which had previously taken over RoboHelp. RoboHelp used to be the prime product for online help, competing against Doc-to-Help. But Doc-to-Help was unfortunately married to Microsoft Word and inherited all of that products’ problems. RoboHelp had reuse and modularity written all over it, but due to bad marketing decisions, or lack of development money, or extreme short-term planning or some combination of those factors, it was sinking fast. Everyone had the impression of a great product being driven into a ravine for no reason at all (except maybe for wanting to squeeze too much money out of the market). When core development on a product stops in a fast-moving business domain, the product is already considered dead, as all investments in it seem to be wasted from the beginning. (Madcap Flare was subsequently created by a bunch of the top developers who had previously created RoboHelp to fill this gap).

So when Adobe got their hands on RoboHelp as part of the dowry that came with MacroMedia (who had no idea what to do with a product for a tech writers market), some clever strategists at Adobe must have seen the potential of combining Frame and RoboHelp, not into one product, but into the newly conceived Technical Communication Suite. When this was first released, I was pretty confident that FrameMaker was here to stay, and would be soon revived from its zombie state. With FrameMaker 9 things improved enormously, albeit mainly with the user interface. Still, that was an important signal that FrameMaker was here to stay: the user interface was finally brought up to modern standards, with many modular dialog windows disappearing and the user having much more control over that interface. When it came out I immediately moved to FrameMaker 9 and have been very happy with the new work environment. Some of the technical improvements were nice to have, but as far as DITA is concerned, there was just minimal support and that did not do it for me. Still, people working in different business domains might have found it good enough. For me, DITA 1.1 was pretty useless due to the concentration on the software industry and lack of support for my kind of machinery service manuals. So I basically built my own DITA machinery task in a Frame EDD and was quite happy and successful in implementing this setup for a couple of regular customers.

With FrameMaker 10, the structured side of the product has received major improvements, including DITA 1.2 implementation, a DITA specialization wizard, S1000D, a much better element attribute editor and a CMS connection manager. An important feature of FrameMaker these days is the conversion tool, which allows you to convert format-based documents into structured documents without a whole lot of work. Basically, if you have always been using paragraph and character formats in a decent manner, with no exceptions or local overrides, it is almost a piece of cake to automatically transform your format-based Frame documents into structured documents. From there, the transformation to XML is, relatively speaking, a piece of cake. I am not sure how good other transformation processes are, but from the fact that there are companies that specialize in migrating to DITA, I have the impression that automatic conversion is not part of many existing editing environments today.

Given the enormous amount of legacy documents that were written in FrameMaker, there is a business case for incorporating some conversion mechanism into a new technology. That is what Adobe has done well. And with the importing options from (format-based) Word into FrameMaker (again, relying on your writers to use formats with no overrides in Word for its efficiency and amount of post-conversion editing that is required), you might even be able to move your Word content into DITA without too much pain.

DITAWriter: Since you’ve been on both sides of the Atlantic, attending DITA conferences in both Europe and North America, what are the key differences you’ve observed in DITA adoption? I certainly got the strong impression while at the last DITA conference in Vienna that adoption rates in Europe are much lower than in North America. Any thoughts on why that might be?

Jang: I think it is true that adoption of DITA in Europe is very much behind that in North America. One of the reasons for this I think is because the software industry is based mainly in North America, and DITA has been good for the software industry from the start. Not only does it include many specializations specifically for software, also it uses similar lingo that is well-known in that industry. Not unimportantly, cool stuff in the software industry smells of geekishness from miles away. I think the adoption of DITA within the software industry would be harder if it were a much simpler technology. Simple is not cool enough for geeks, to state things bluntly.

There is also a cultural difference between North America and Europe: American culture is more technology-oriented, where European culture is use-oriented. A simple example is the cell or mobile phone. Americans say cell phone, we say mobile phone. The cell refers to the technology required to keep connections while the phones are moving from one location to another. The European term does not say anything about the technology, just about the use of the phone: you can take it with you from one place to another. If I would have more time I would be able to find a lot of examples of this cultural difference. The point is that the worldview of an average North American is more technology-oriented than the worldview of an average European, for whatever reasons this may be the case. A stronger orientation toward technology brings down the threshold for a new technology like DITA to be adopted.

DITAWriter: What are you planning on talking about at the next DITA North America conference coming up in Baltimore next month?

Jang: The talk will be basically the same one that I did in Vienna, but with demos of the constraints mechanism in practice at the end. I am working on a demo using FrameMaker 10 and would also like to include a description of how to handle things with the DITA Open Toolkit – but I am not sure whether I will have time for all of this.

I am still looking for tools that would meet my requirements as a potential non-DTD-savvy user to create constraints in a visual manner, using checkboxes and drag-and-drop interfaces to define the constraints and then shooting them into the right positions in the file system to make my XML editor work with them. A few candidates do some of that work, but not one tool does it in the way I would like it to.