Picking Up the Pieces

I  completed a writing assignment with a  small startup company where I revamped the approach to  product documentation to emphasize short article-length documents that are preferred for posting to the Web (as if anyone really read book-oriented PDF documents cover to cover anyway).

The company that hadn’t made revisions to their existing product documentation in over a year (and is planning for a new product release real soon now). It’s the same startup where I spoke to the engineering manager about the use of open source authoring tools (see my post Bottom Line). The discussion eventually evolved into my proposal to use open source software as a “free” (or at least low-cost) alternative to the expensive per-user licensing and support contracts that are required for commercial tools such as FrameMaker and RoboHelp. In a time when companies need to get the biggest “bang for the buck”, OpenOffice (or variants such as StarOffice and Lotus Symphony) may be all that a small to medium sized company needs to create the short article-length documents that are preferred for posting to the Web (as if anyone really read book-oriented PDF documents cover to cover anyway).

So, I started with a situation where there were no source files for the documentation that shipped with the last software release, no clear idea of which versions of the authoring tools  were used, and no real incentive to spend the $999 for the current version of RoboHelp or FrameMaker. My first real task was to take the last available FrameMaker 7 source documents archived from an older software release, buy an older compatibile version of FrameMaker (at only $499), and eventually export RTF files that could be used with OpenOffice before any updates and revisions could actually be incorporated. Along the way, I contended with authoring tools issues (such as template formatting, conditional text, and PDF export) that are not within the expertise of the average technical writer, and I found that the “free” technical support to be minimal.

Once I managed to break apart the book-length manuals into manageable chunks (approximating a chapter in length and topic organization),  I found that OpenOffice provided the flexibility to export the content to the project team to review and update in wiki format (moinmoin is what is used here), then I could take those revisions and updates to create PDF files to post on the company web site, as well as serve as the basis of an “old school” browser-based online help set that uses standard HTML tags (framesets) rather than rely on fancy JavaScript or ActiveX controls.

A pleasant benefit of using open-source software such as OpenOffice  is that no expensive upgrade was required in order to extend OpenOffice with the ability to import and export PDF files (included in version 3.1) or to import and export wiki formats (contributed by community members). Perhaps the needs of the startup where I work are not as complex as my former employer that maintained a large knowledge base with expensive single-source structured authoring tools. However, through the collaborative efforts on open source software, the bottom line seems to be that low budget does not necessarily mean low tech.


2 responses to “Picking Up the Pieces

  1. John Domenichini


    I really enjoyed this blog entry. This is relevant stuff.

    John D.

  2. Joe, it’s really a great post. I think, tech writing is moving away from the traditional way of content generation. Breaking down the information and making it searchable units is the key here. I have never gone through the user manual of a gadget that I bought unless it is an absolute necessary. I think, information in need is indeed a boon, irrespective of the format in which it’s delivered. Even a text format will do. Anything that comes free is of less quality is a wrong notion. Many of the open source products are stable and provide great support to companies. Similar to the doc tools that you mentioned, the testing tools, such as Selenium, JMeter, Emma, and so on can help companies to save a lot of money in this tough time. I think it’s more of a mindset that makes people to doubt the quality of open source tools.

    Kudos to the great job you did. Thanks for sharing it with us.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s