On DITAWriter I like to provide a voice for those who are working with their own DITA implementation, and the particular issues that they face. All technical communication groups face their unique documentation situations, so the tools needed for the job will vary by need. Mr. Linarez’s technical documentation group opted for DITAToo, an “up-and-coming” DITA Component Content Management System (CCMS) combined (in this case) with Adobe FrameMaker.
Mr. Linarez pulls no punches in this interview—this is a good place to remind readers that his opinions are his own and do not represent the firm he works for—and while I thought about removing the names of the products he didn’t like, but his opinions are his own and I believe people will be able to recognize if their situation is similar enough to his and make allowances accordingly. It also makes for a better interview!
DITAWriter: Could you tell me a little bit about yourself and your role at Pelco/Schneider Electric? What types of technical documentation do you and your team produce?
Linarez: I’ve been with Pelco/Schneider Electric for nearly nine years now. My current position is Tools/Platform Development. Basically I take care of, and make recommendations on different technologies in our department depending on our needs. I also take care of various random tasks that involve our website, and releases of documentation.
Our group is responsible for the bulk of published material that ships with our products. This consists of manuals and specification sheets for the most part, though we also create some other documents when requested.
DITAWriter: Prior to moving over to DITA, what was your documentation workflow like? What made you and your colleagues decide that something needed to change?
Linarez: Prior to moving to DITA, our workflow was primarily managed through PTC Windchill. Everyone hated it. It was a linear workflow that didn’t give us much wiggle room when we needed to do things outside of their process. That and no one here liked filling out all the small details it required as we were trying to create documents. It just wasn’t practical for us, and didn’t fit our needs.
The real push towards DITA happened because of a new product line. It was for a series of cameras that came in many flavors. Most of the content was nearly identical and what differences there were had to do with the specific hardware and software features that were available. We had tried our hand at single sourcing, but at the time we simply didn’t have the skillset to manage it properly. Quite frankly, we didn’t have a writer organized enough to manage everything by themselves.
Our next step was to use Tortoise SVN so we could at least have a check-in/check-out and revision management, and started the process of writing in a topic-based format. Eventually this became unmanageable as the number of topics grew, and this was the catalyst to finally make the leap for a DITA CCMS. It was more technical and it presented a challenge for some of the staff, but at the same time it created an opportunity for some of our more technical writers to increase their productivity.
DITAWriter: What made you choose DITAToo as your DITA CCMS?
Linarez: Our selection of DITAToo happened as the result of the decision to move to an XML environment. This came months after our initial pilot using a completely different set of software. Though at the time there was a committee making decisions on our direction, I was one of the main voices recommending that we look for a solution that better fitted our group’s needs. We actually didn’t have any documentation being written in XML at the time, due to the fact that our changing documents required versioning and link handling, so the idea was to make the switch at the same time we would acquire a XML-based CMS to contain the data.
The selection process for DITAToo was pretty thorough actually. There are a multitude of software suites that can manage DITA XML. Our first selection pass was based on us wanting to stick with FrameMaker, due to the amount of customizations we would have needed to do otherwise. Stylesheet handling in DITA can be a pain, and FrameMaker is one of the few tools that allows a moderate amount of customization with an actual GUI.
The first few features we were looking for were basic. We needed something that worked well with Frame, a reliable versioning/linking system, translation management of some sort, and ideally ease-of-use (this became a big factor oddly enough, when compared to some bigger offerings from other companies). When it was all said and done, and after various demos, the simple feature set of DITAToo was a perfect match for our needs. Additionally, the cost was a huge plus. It’s a relatively inexpensive tool with a ton of features. The value is just tremendous.
DITAWriter: It sounds like wanting to stick with FrameMaker was a major factor in your CMS decision. While I know that you can work with DITAToo with XML editors like oXygen or XMetaL directly, it is one of those rare DITA CMSes that also works directly with FrameMaker. So how does FrameMaker work with DITAToo exactly? Also, what do you think of Adobe’s recent developments with FrameMaker?
Linarez: Sticking with FrameMaker was a big issue for us. There were multiple opinions on what editor to use, and there were some in the group who were completely opposed to FrameMaker in favor of oXygen. One of the things I have always tried to be clear with people in making decisions like this, is that one has to take a look at each tool and weigh it against the functions in a particular environment. In this case the requirement was the support of DITA in itself, which both tools had. The difference however was our own ability to manipulate the output rendering. While the DITA Open Toolkit is useful, it’s not exactly user friendly when it comes to making customizations, especially complex ones.
Our output here at Pelco/Schneider changes frequently, depending on what the product is and what the requirements are for a particular customer. With the increasing amount of OEM vendors that we have to deal with, we needed a tool that be flexible and allow us to be able to easily make changes to the output. Being able to handle legacy documentation that was not in an XML format as well as being able to use DITA XML, while still being able to manipulate the output was critical for us. If we could have that, and be able to easily customize the output, that was going to be our tool, and ultimately that was the reason why we chose FrameMaker. oXygen is an excellent authoring environment, but in our case it simply was not a fit for us.
As far as Adobe’s recent developments with FrameMaker, that’s a mixed bag for me. I understand that they are trying to push a faster development cycle, but the truth is that some products need time to mature. For example, we made the change from FrameMaker 11 to FrameMaker 12, and what we found was that FrameMaker 12 does everything FrameMaker 11 did, just better. The truth is that it feels like a “polished” version of FrameMaker 11 rather than something that would warrant a new version.
Unfortunately a lot of companies are moving in this direction and it’s something we just have to deal with. The Adobe subscription model is another issue. While their Technical Suite looks great, I wish most companies (take SDL for instance), would stop trying to get people into an entire software ecosystem managed by them. I get the financial aspect of it, but often it’s best to just cherry pick the best tools that fits your situation. There is no “one size fits all”, at least not in my experience at most companies. So to me they are not doing themselves a favor and are trying to offer too much—at a premium—to customers that simply may not want all those features. But making an XML-authoring version of FrameMaker was definitely a step in the right direction, though we use the “full” version of Framemaker.
DITAWriter: What has been your experience with DITAToo as a company?
Linarez: My interaction with them has been fantastic. I couldn’t tell you about other firm’s experiences with them, but at least for us the communication has been frequent and positive. I am actually surprised they don’t advertise this as a plus. When we first acquired DITAToo, we had a few issues with the setup. All of their responses happened within 24 hours despite the large time zone difference, and eventually this led to a pretty open dialogue regarding features and future revisions.
Some of the changes they have added are actually due to our requests. I can’t say it was specifically requests made by us, but when you see changes that are very similar to things you have asked about, it clearly shows that they are paying attention. This sort of thing isn’t common in my experience. This may be due to the fact that they are a small company, but I am hoping that it continues as they grow. It’s actually fun seeing this product develop and feeling like you have a say in it. It just makes it that much more useful.
DITAWriter: If you knew a year ago what you know now, what would you have done differently? What advice would you give to anyone just starting down the path of DITA?
Linarez: If I knew a year ago what I know now I would say that our decision to use DITAToo would have been exactly the same. The only thing I would have changed—which has nothing to do with the CMS selection—is the choice of additional tools that we could have used alongside FrameMaker.
The best advice I could give to anyone moving to DITA XML and managing it is relatively simple: DITA may seem restrictive but it isn’t, and the only real restriction is how a team decides to use the data. Because a lot of the content produced is reusable, any team moving to DITA should look for a tool that actually has features they can easily use, and stay away from bloated feature sets that either complicate the functionality they are looking for, or would slow down their productivity. This was a big issue I had with the other software offerings. A lot of CMSes rely on a web interface, that while it may seem convenient, it is extremely slow when compared to a locally-run and managed database.
For a user, the interaction of the authoring environment to the CMS needs to be seamless, and this is something that DITAToo just crushed the competition with. The writers also enjoy using the tool which also means that our productivity is better.
