Communications from DMN 

Pros and Cons of Open Source Doc Tools - January 15, 2007





This is Communications from DMN for for the week of January 15, 2007.

Scott

I'm Scott Nesbitt.

Aaron

And I'm Aaron Davis. Thanks for joining us for this podcast.     

Scott

We've got a lot to talk about this week. First off, Aaron has some great news that he's dying to share.

Aaron

Absolutely. I'm happy to announce that DMN Communications has been invited to speak at the 8th Annual Documentation and Training Conference, held April 18 to the 21 in beautiful Vancouver British Columbia. This is the first time that this conference has been held on the west coast and the first time in Canada, so we're excited to be a part of it. The theme of the Vancouver conference is The User Experience, and Scott and I will be giving a talk called “Getting a Foothold: Using Basecamp to Improve Productivity and Collaboration.” We'll be explaining how to use the Basecamp online collaboration tool to keep documentation projects on track.

Now, if you're a regular listener to this podcast, you may remember us talking about Basecamp last year. Our talk in April will expand upon the original podcast to discuss how communicators, managers, and contractors can use Basecamp to stay organized, to monitor time spent on each facet of a project, to simultaneously manage multiple projects and deadlines, and much more.

Just to let you know, we're not being paid by 37 Signals to sell Basecamp nor do we have a consulting relationship with them. That's not to say we wouldn't like to! In any event, during the course of our talk, we'll be offering tips and techniques that you can use, regardless of the tool that you intend to use to manage your project.

OK, another quick housekeeping item... over the next few weeks, we're going to be quite busy with preparing for the Documentation and Training conference so there's a possibility that the podcast might be a couple of days late once in a while. Keep an eye on this space and our blog for more information. So, Scott, is this great news or what?

Scott

I'm really excited to present what we hope is a fresh perspective on managing documentation projects. The conference should be an interesting and fun time. Ever been to Vancouver?

Aaron

You know, I haven't, and I've been meaning to for awhile. My brother lives in Vancouver so I'll probably spend a day post conference visiting and catching up. If you're going to be at the Documentation and Training conference in Vancouver, feel free to stop us and say hello. Tell us what you think of the Communications from DMN podcast.


OK, on to the main part of the podcast. Our focus today is discussing the pros and cons of Open Source documentation software. You can find links to any articles that we cite or software that we mention in the transcript of this edition which we'll mention at the end of this podcast.


Scott and I make no secret of the fact that we're big fans of Open Source software. We regularly use tools like OpenOffice.org, Mozilla, and others. What do you think? Are Open Source tools for authoring and publishing documentation ready for prime time?

Scott

Before we get going, let's add some perspective to this discussion. Last year, Linux.com published an article on why technical writers don't use free and Open Source software.

The conclusion was that many technical communicators either don't know about the available authoring tools or don't want to make the move. To answer your question Aaron, some Open Source tools are ready for prime time and others aren't. It really depends on the maturity of the tool and how it is used.
Aaron
 I think that whether or not you should make the move to Open Source is a matter of debate. Here's another question. Does anyone actually use Open Source tools to authoring and publish documentation?
Scott
 Well, you probably won't be surprised to learn that most Open Source and free software projects use those kinds of tools for their documentation. And a large number of companies do, too. Many of them use DocBook and its toolchain. Others, DITA and the DITA Open Toolkit. A good example is database maker MySQL. For the longest time, the company used the LaTeX typesetting system to author and publish its documents. Now, they use DocBook, which has really enhanced the look and the flow of the docs.

Of course, there are other tools, too. Most of them are based on XML or on some markup language, like AsciiDoc
Aaron
 OK. But one of the main criticisms that I can make is that there are no Open Source equivalents of standard software -- apps like FrameMaker, RoboHelp, Flare, and so on. There's really nothing on the Open Source side of the fence that offers you the same power and flexibility. And, as far as I know, there are no Open Source applications that can exchange files or interact with industry standard tools.
Scott
 Good point. Then again, if you're using an XML-based format like DITA or DocBook, you can work with your files in tools like FrameMaker or XMetaL. And you can edit these files -- and others created using markup languages like AsciiDoc or AurigaDoc -- in any text editor.
Aaron
 True. But who really wants to manually add markup in an editor? I can't think of any WYSIWYG or near WYSIWYG Open Source editor that's good enough to use for creating documentation using markup. Nothing comes close to XMetaL or even XXE.

Single sourcing is another issue. DITA and DocBook can output to multiple formats and allow you to conditionalize the text for your target audience. Is there anything on the Open Source side of the fence that can do this?
Scott
 AurigaDoc, which I mentioned earlier, can. It's an XML-based format that can save source documents to multiple formats -- including HTML, PDF, and various forms of online help. And the newest version supports conditional text, which the developers call profiling. How very DocBook ...

Of course, if you're just doing print or PDF documents there's OpenOffice.org Writer ...
Aaron
 OK, wait a minute. After all the trouble that both of us have had in the past using Word to write docs, now you're bringing up a word processor? Seriously, though, what does OpenOffice writer do better than Word?
Scott
 For one thing, there's stability. OpenOffice.org Writer handles long documents better than Word and has a solid conditional text feature. It's not quite as robust as FrameMaker, but then again what is. OpenOffice can be a pretty good alternative, especially if you're a contractor and your clients are OK with you using it. In fact, there was a review a year or so ago in which a technical communicator compared Writer and Frame and found that Writer was a pretty strong contender.
Aaron
 Oh yeah, I think I have that bookmarked somewhere. It's definitely something to look at a little bit more closely if you're searching for an open source alternative to Word and FrameMaker.

OK, let's switch gears and talk about help authoring. I think this is an area where Open Source tooling falls flat. There's really nothing that can compare to the software that technical writers commonly use for online help. I have yet to find an Open Source help authoring app that integrates with FrameMaker or even OpenOffice.org Writer to produce help content.

The Open Source tools that we've worked with or tested are really help authoring GUIs. They don't take into account the fact that authoring help is rolled up in the task of authoring a manual. It's the single sourcing strategy that you use which makes the difference, and the Open Source tools force you to maintain two versions of the documentation. What a nightmare.
Scott
 I definitely agree with you there.  Really, the only technologies that come close are DITA and DocBook. They both output HTML based help. And there used to be a DocBook stylesheet that generated a WebHelp system. But that seems to have disappeared off of the Web.
Aaron
 So, for the most part, it's safe to say that Open Source tools for creating documentation aren't quite there yet. In the case help authoring, they've got a long way to go. There are certain tools, like OpenOffice.org Writer and AurigaDoc, that support conditional text. But most of the tools seem to be predicated on the old school method of single sourcing: one source, but multiple formats of the same text.

That's not to say you can't use Open Source applications to author documentation. At this point, if you're thinking of making the move to Open Source, you should consider the size of the project and research the Open Source alternatives to see if they meet your needs in terms of features, functionality, and flexibility. That's not to say that you can't use Open Source applications to create technical documentation - just that it is important to realize the limitations of doing so.

Scott

Now it's time for our Pick of the Week. Each week we choose a book, Web site, or blog that we find interesting and useful and hope that you will, too. This week we're plugging the competition: the podcast Tech Writer Voices.

Aaron

Yeah, I really like both the blog and the podcast which I regularly download and listen to on my BlackBerry to and from wherever I'm going. Tech Writer Voices discusses a wide range of topics that are of interest to the technical communicator. Everything from single sourcing to tools and trends to usability. And quite a bit more. Tom Johnson, the president of the STC Suncoast chapter in Tampa Florida, talks to industry experts and posts the podcast entries of others. The podcasts bring unique and interesting perspectives to the topics discussed. The podcasts that I've listened to have never been boring, and I've even learned a few things along the way.

Tom Johnson also has a blog which nicely complements the podcast, too. Check it out. Tech Writer Voices at www.techwritervoices.com.

Scott

That's all we have for this edition of Communications from DMN. Join us next week when we discuss bad software and how it effects documentation, and what you can do about it.


Thanks for listening. If you have any questions, comments, or suggestions for future podcasts drop us a line at podcast@dmncommunications.com. And don't forget to visit our Web site (www.dmncommunications.com) and our blog (www.dmncommunications.com/weblog).

Have a good week.