WindowsDevCenter.com
oreilly.comSafari Books Online.Conferences.

advertisement


AddThis Social Bookmark Button

Technical Writing Using OpenOffice.org Writer
Pages: 1, 2, 3

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.