Windows DevCenter    
 Published on Windows DevCenter (http://www.windowsdevcenter.com/)
 See this if you're having trouble printing code examples


Technical Writing Using OpenOffice.org Writer

by Jean Hollis Weber, author of OpenOffice.org Writer: The Free Alternative to Microsoft Word
08/24/2004

Technical writers produce a wide range of documents, such as data sheets, specifications, user guides, online help, marketing materials, proposals, tenders, reports, and more. Although the final layout of many of these documents is often done using FrameMaker, PageMaker, or QuarkXPress, far more documents are produced using Microsoft Word.

If you're in the business of writing technical documents and you've been using Word in particular, you could benefit by switching to OpenOffice.org Writer. OpenOffice.org Writer is a strong competitor to Word for both drafts and final layout (desktop publishing) of many technical documents because it combines some of the best features of Word and FrameMaker. Indeed, Writer does several things better or easier than each of them, as I'll discuss in this article. I cover this information in more detail in my book, OpenOffice.org Writer: The Free Alternative to Microsoft Word (O'Reilly Community Press, July 2004). I created the book using OpenOffice.org and output it to PDF for printing.

A Tech Writer's Toolbox of Features

OpenOffice.org (OOo) is an open source application that runs on Windows, Macintosh, Linux, and Solaris. The application includes several components: a word processor (Writer), a spreadsheet utility (Calc), a presentations program (Impress), and a drawing function (Draw). It is available for download from the OpenOffice.org site. OOo documents are zipped files containing XML files and graphics files.

In addition to all the usual features you'd expect to find in a word processor (such as a spell checker, wildcard search and replace, embedding and linking of spreadsheets and graphics, the use of headers and footers, automatic tables of contents and indexes, and many others), Writer has many features of particular interest to technical writers. Here are a few of them:

Let's look at the good (and a few bad) points of each of these in a bit more detail.

Related Reading

OpenOffice.org Writer
The Free Alternative to Microsoft Word
By Jean Hollis Weber

A Customizable Interface

If you plan to use Writer a lot, you'll want to take the time to set up the interface to suit your work and your personal preferences. Writer's default options at installation include some automatic features that you'll probably want to turn off. Many of these are found in Tools -> Options; others are in Tools -> AutoCorrect/AutoFormat. You can also change the menus and toolbars using Tools -> Customize.

Document Templates

Templates can store styles, text, graphics, and user-specific setup information such as measurement units, language, the default printer, and toolbar and menu customization.

You can create as many templates as you want--at least one for each type of document you produce. When you start a new document from one of these templates, much of the setup work is already done for you. If you wish, you can modify individual documents so that they are different from the template on which they are based. For example, you can include logos and standard text such as an address or a legal notice in the template, but you might not want them in every document based on the template.

All Writer documents are based on templates. If you don't specify a template when you start a new document, the document will be based on the default template for text documents. If you haven't specified a default, Writer uses the blank template that is installed with the program.

You can specify any template as the default template for text documents, and you can quickly and easily change the default template at any time. Changing a default template has no effect on existing documents.

Template handling has some features that I hope will be improved in a future release. For example, Writer provides two ways to save templates, but the consequences differ. If you use File -> Templates -> Save, any document subsequently based on that template will retain an association with the template. (I call these "sticky" templates.) If you use File -> Save As -> Template, documents based on the template will not retain an association with the template.

So what? you may ask. When you change a sticky template, the next time you open any document based on that template, you can choose to update the document's styles from the template. This feature is important if you want your documents to always reflect the latest changes to a template. Large projects, including master documents, and projects with more than one writer typically make extensive use of templates in this way.

Another problem is that Writer does not provide ways to attach a template to a document after the document is created, or to change the template attached to a document. In both cases, you'll need to create a new, blank document from the required template and copy the old document into it, or you'll need to use Format -> Styles -> Load to import styles from the new template into the document. Both methods work, but they are cumbersome.

My book covers some of the other template limitations. Despite these issues, templates work well, and most problems are a matter of learning some slightly different techniques than you've been used to in Word or another program.

Styles

A style is a set of formats that you can apply to selected pages, paragraphs, characters, frames, and other elements in your document to change their appearance quickly. When you apply a style, you apply a whole group of formats at the same time. Thus you can easily ensure consistency in page layout and the appearance of headings, captions, lists, graphics, and other elements. More importantly, you can quickly and easily change that appearance by changing the style in one place; all the elements tagged with that style will change immediately.

Writer supports styles for pages, paragraphs, characters, frames, and numbering. It comes with several predefined styles in each category. You can modify these styles, and you can also define custom styles. You can use any combination of styles to suit your document, and you can also override styles for specific paragraphs if you need to (such as tagging specific paragraphs to be kept with the subsequent paragraph).

Page styles define the basic layout (paper size, margin widths, placement of headers and footers, number of columns, and so on) of all pages in a Writer document. You can have one or many page styles in a single document; for example, you can define styles for the first page of each chapter, left and right pages, index pages, contents pages, landscape pages, and any other pages you might need. If you don't define your own page styles or choose one of the built-in styles, Writer uses the default page style supplied with the program. Although not as powerful as FrameMaker's master pages, Writer's page layout handling is more versatile than Word's.

Paragraph styles control all aspects of a paragraph's appearance, such as text alignment, tab stops, line spacing, spaces before and after the paragraph, first line indent, borders and shading, and a character style for the paragraph. If you plan to use Writer's table of contents feature, you'll need to be sure to tag all headings with appropriate paragraph styles (either the built-in ones or those you create yourself) so Writer can identify which paragraphs are headings. Tagging other paragraphs with specific styles, instead of using manual overrides, can also help you maintain consistent presentation--especially if you need to change any aspect of that presentation, such as the font size or the space before or after the paragraph.

Character styles affect selected text within a paragraph, such as font, size, boldface, italics, superscript, and other characteristics. These styles are particularly helpful for tagging items such as the names of controls on a user interface or perhaps a product name, but this usage is often overlooked. I learned the value of character styles the hard way while writing my book. I didn't use styles for these items; instead, I manually made bold the name of each menu bar item and toolbar button. When my O'Reilly editor asked me to remove the bold, I had to use search and replace to make the changes; then I had to look through the entire document to make sure I hadn't missed anything. If I had used a character style for those items, I could have changed them all instantly by simply changing the style.

Frame styles are used to format graphic and text frames, including wrapping type, borders, backgrounds, and columns.

Numbering styles apply alignment, fonts, and number or bullet characters to numbered or bulleted lists, and they outline numbered paragraphs such as headings. They are useful for a variety of purposes, including complex numbering schemes and dramatic layouts that involve large, bold numbers or graphics for bullet points.

Page Layout

You cannot change the underlying page style for an individual page, but you can control page layouts by using combinations of page styles, paragraph styles, tables, columns, and frames. Well-planned combinations can provide consistency throughout a document while allowing differences when needed; if you're creating a complex layout (for example, for a newsletter), Writer provides the flexibility you need.

After you have set up your basic page styles, you can look at the finer details of page layout. In many cases, you can control page layout by using paragraph styles alone. For example, you can define heading paragraphs to be flush with the left margin and paragraphs for text or graphics to be offset from the left margin.

In some cases, you might need to use other methods to place text or graphics where you want them. One of those methods is to use tables to position various page elements or to line up graphics or side heads in the margin with specific paragraphs.

You can also use columns for page layout, and you can switch between single- and multiple-column layouts on the same page. Columns can be of equal or unequal widths.

For complex layout purposes, you may find that frames are a better choice, because you have more control over the placement of text. Frames can be very useful if you are producing a newsletter or another layout-intensive document. Frames can contain text, tables, multiple columns, pictures, and other objects. You can link the content of one frame to another so that the contents flow back and forth between them as you edit the text.

A Change-Tracking Feature

Writer's change-tracking feature records who made which changes to a document. It is valuable when you are collaborating with other contributors to a document or when a document is edited or reviewed.

Writer's change-tracking feature is similar to Word's and thus is better than FrameMaker's. Although it has some minor irritating features, change tracking works well in Writer.

Master Documents

When working with large or complex documents (such as a book, a thesis, or a long report), you have two choices: keeping the entire document in one large file or breaking it up into a series of smaller ones. Each approach has its advantages and disadvantages. Smaller files are most useful when graphics, spreadsheets, or other included material causes the file size to become quite large, or when different people are writing different chapters or other parts of the document.

If you choose to use smaller files, you can often combine them into one large file at the end of the project before generating the table of contents and index. Another approach is to use a master document.

Yes, master documents do work in Writer--quite well, in fact. However, their use is full of traps for inexperienced users. Until you become familiar with the traps and how to avoid (or work around) them, you may think that master documents are unreliable or difficult to use.

You can use several methods to create master documents. Each method has its pluses and minuses. The method you choose depends on what you are trying to accomplish. In my book, I describe each of these methods and their good and bad points, and I give an extended example of how to set up a master document for a book with complex page-numbering requirements.

Fields

Technical writers typically use fields to hold information that changes (so that it can be easily updated), to create cross-references to other parts of a document (so that those references update automatically when the target's text or page number changes), to insert document information into headers and footers, to create custom numbering schemes, and for other purposes.

An annoyance for many people is Writer's lack of an automatically generated list of headings for use in cross-referencing. Instead, you must individually tag each heading (or other text element) as a target for cross-referencing. However, if you're accustomed to bookmarking items as targets instead of using a built-in list, then you'll find this feature to be quite familiar.

Other than that annoyance, fields work well and are quite versatile.

Conditional Content

Conditional content is material that is marked so that it can be included or excluded from a document depending on a condition you specify. An example is a software manual for a product that comes in two versions, pro and lite. Both product versions have much in common, but the pro version includes some features that are not in the lite version. If you use conditional content, you can maintain one file containing information for both versions and print manuals (or create online help documents) customized for each version. Because you don't have to maintain two sets of the same information for both versions, you won't forget to update both versions when something changes.

One major advantage of Writer over Word is that Writer supports conditional content. Word doesn't, although you can use various workarounds to achieve a similar result. Thus Writer has incorporated one of FrameMaker's major attractions for technical writers, although Writer's implementation is more limited than FrameMaker's.

Writer handles conditional content in a few different ways:

  1. Conditional text (two alternative words, phrases, or sentences), where one item is displayed and printed if the condition you specify is met, and the other is displayed and printed if the condition is not met. For example, the names of the pro and lite product versions can be set up as conditional text.

  2. Hidden text (a word, phrase, or sentence), where you have only two choices: show or hide. If the condition you specify is met, the text is hidden; if the condition is not met, the text is displayed. For example, text relevant only to the pro version would be hidden for the lite version.

    Hidden paragraphs are like hidden text but are entire paragraphs.

  3. Hidden sections can include graphics, fields, and formatting. The contents of a hidden section behave just like the contents of any other part of the document, but you can specify a condition under which the section is not displayed or printed. You can also choose to display the section but not print it; and you can password-protect a section.

A Bibliography Database

A bibliography is generated from bibliographic entries that you insert into a document either directly or from a bibliography database associated with the document. If you expect to use bibliographic entries in more than one document, you'll save a lot of time (and improve consistency) by creating and using a bibliography database (Tools -> Bibliography Database).

Writer makes this process easy, but it has some limitations. The biggest problem for some people is that you can't define more than one "short name" that will appear in your document when you insert a bibliographic reference; Writer uses the identifier for the database entry as the short name. Therefore, if you use the database to prepare documents that require different "short name" reference styles, you'll need to use some workaround for this limitation. For most people this isn't an issue, and if you number references within the text (for example, [1]), the short name doesn't matter.

Use the Insert Index/Table dialog to define the text reference delimiters and style as well as the appearance of the generated bibliography. The formatting choices are many and varied; setting them up to suit your needs may be tedious, but the time spent will pay off in the consistency of presentation and the ease of generating an end-of-book or end-of-article bibliography.

An Equation (Formula) Editor

OOo's equation editor isn't as robust and versatile as MathType, but I've heard good reports from mathematicians and others who use it extensively. Unlike Word's equation editor, Writer's is included automatically with the standard installation of the program.

When you choose Insert -> Object -> Formula, you open a separate OOo Math window in which you can compose your equation.

A Macro Language

Writer has a full macro language (OOo Basic), typically used for automating things you do repeatedly (to save keystrokes), for creating fill-in forms, and for a wide variety of other functions. OOo Basic is not the same as the language Microsoft Office uses (Visual Basic for Applications), but it has the same functionality. A recently published book by Andrew Pitonyak, OpenOffice.org Macros Explained (Hentzenwerke, 2004), provides an in-depth description of the macro language.

PDF Exporting

OOo provides a simple way to convert files into Portable Document Format (PDF), to be read by Acrobat Reader and other programs. The process generally produces good results, but you don't have the same control over those results that you do when using Adobe Acrobat to create PDF files. The Help file gives details of the built-in settings, which you cannot change. The biggest limitation is that files converted to PDF using OOo, either by using its built-in export-as-PDF function or by printing to a PostScript file and distilling using Adobe Acrobat, do not have bookmarks or working internal links like they do when created from Word or FrameMaker. This limitation may be a showstopper for some requirements.

Microsoft Office Compatibility

If you need to share documents with users of Word, you can open Word files in Writer, edit them there, and save them as Word files. However, if you have used any of the powerful features of Writer (and sometimes even when you haven't), the output may not be quite the same when it's read by Word. Although some files will go back and forth between the two programs without major problems, other files definitely won't. It depends on which features of Word and Writer you've used.

In general, document contents convert fine, but layout may suffer and some fields are changed into text. If Writer doesn't support a feature of Word, Writer will make a substitution that may or may not be what you want. For example, Word's Styleref field, used in the headers and footers of many technical documents, is one that doesn't convert, because Writer doesn't have an equivalent field.

If your publication process uses one program (such as Word) for drafts and another for final layout, you'll probably find that Writer can easily be substituted for Word in the workflow.

If you need to convert existing documents from Microsoft Word to OOo Writer, OOo provides a batch-import function to assist you. However, Microsoft Office and OOo cannot run the same macro code. Office uses Visual Basic for Applications (VBA) code, and OOo uses StarBasic code, which is based on the OpenOffice.org API environment. OOo can load the macros in Office files, and you can then view and edit the macro code in OOo.

Some Observations

Whether you'll find OOo suitable for your work depends on what you do and what features you'll need to use. I've found Writer to be more compatible than Word with my working style and the requirements of documents I produce, once I got used to it. Most of the problems I've mentioned don't affect my work, but I can see situations in which they could present problems for other people.

Although Writer has crashed on me a few times, it has never corrupted my file, and it usually recovers all but the last few changes I've made. It's dealt with large, complex files without slowing down unacceptably.

Any other minor complaints I have with the program are known issues, many of which are being addressed in the next major release (version 2.0), expected in 2005.

Conclusion

I've looked briefly at a few of OpenOffice.org Writer's powerful features and their use by technical writers. If you use Word, you'll probably find that Writer can do the job just as well if not better, once you get used to its different approach to many things. However, you'll need to evaluate whether Writer's features and limitations are suitable for the requirements of your documents and working environment.

Jean Hollis Weber has worked as a technical publications consultant for the past 12 years. She has written books, taught short courses in technical writing and editing, and presented parts of graduate and undergraduate courses at several Australian universities. She maintains several web sites, including one for technical editors and one about OpenOffice.org.


O'Reilly Media, Inc., recently released (July 2004) OpenOffice.org Writer .


Return to WindowsDevCenter.com.

Copyright © 2009 O'Reilly Media, Inc.