I am a technical writer, and I am using FOSS

I am a technical writer, and I am using FOSS


This story, Why technical writers aren’t using FOSS, appeared in on Newsforge in April, and I have to take issue with some of the assumptions.

First of all, I am technical writer, and I do use FOSS—in fact, I’m a technical writer that documents FOSS technology using FOSS tools.

At MySQL, where I am a member of the documentation team, we use DocBook XML to build the documentation that you see on the website, or that’s available through the PDFs that can be downloaded. In fact, you can even download the XML source we use.

The XML is formatted using standard tools, and we use Apache FOP to translate the output into the various formats.

For many of my other writings—see MCslp.com—I use FOSS software when available or appropriate for the client or target in question. Here at Free Software Magazine, submissions are in XML, and what tool you use for that is entirely up to you.

I use emacs a lot, although for most XML work, including MySQL, FSM, ServerWatch and some IBM work I’ll use the <oXygen/> XML editor. It’s not FOSS, but it is a very good piece of XML editing software. Most of my book publishers, however, still use Word. I could use OpenOffice.org, but as a Mac user, I prefer to ensure that the application I’m using is 100% compatible with the publisher’s systems, and I see no reason to use FOSS software when I own licenses for the same applications my publisher uses.

As to the comment from the original article:

Another point that may be difficult for members of the FOSS communities to understand is that, although tech writers often keep typically long corporate hours and may work alongside FOSS programmers, few express any inclination to learn more about computing or to gain more control over how they spend most of their days.

I really have to take issue. I do not remotely believe that the majority of technical writers are technically ignorant. Many of them are writing on technical topics and—certainly in the case of the majority of people I work with inside and outside of MySQL—we all come from a heavy computing or programming background. In fact, I’ve spent my life trying to get away from programming, even though for the last seven years, I’ve spent 100% of my life writing about programming, or simply writing software like Cheffy.

I really can’t agree with the article, if taken on the title and some spots of content. In reality though, if you read the full article through, it seems to be more of a “Why aren’t FOSS tools as good as commercial ones”, using us technical writers as justification for why that might be the case.

Category: 

Comments

David Sugar's picture

I start from latex, and transform that as needed to html, pdf, etc. But it is a pain to edit and maintain that way, although xml is not immediately a perfect solution on it's own either, as it is designed for machine parsing more so than human reading :). I would love to start from an editor that produces transformable xml for feeding to other formats, and with the backend transformation tools. I have this starting from tex today.

Author information

Martin Brown's picture

Biography

Martin “MC” Brown is a member of the documentation team at MySQL and freelance writer. He has worked with Microsoft as an Subject Matter Expert (SME), is a featured blogger for ComputerWorld, a founding member of AnswerSquad.com, Technical Director of Foodware.net and, and has written books on topics as diverse as Microsoft Certification, iMacs, and free software programming.