Is OpenOffice the Right Tool for Techwriters and Book Production? (Repost)

   

Originally published in fall 2005.

Note: See also this article by Bruce Byfield.
http://www.techwr-l.com/techwhirl/magazine/technical/replaceframewithwriter.html

OpenOffice.org as a Techwriter's Tool for Making Books
Let's get this out of the way up front. I use Framemaker for all my OpenOffice.org workbooks and books. It's just a better tool for books than both OpenOffice.org and Microsoft Word. Framemaker has conditional text, extraordinary cross-referencing and numbering tools, solid, reliable layout features, conditional text (which I use extensively), and much more.

So if you're using Framemaker now, you like it and understand it, you use a lot of cross-references, and you do books of even moderate complexity, I say to you, don't be an open source hero. Stick with Framemaker.

If you're not sure whether you need Framemaker, read on and see what you think.

If you're on Microsoft Word, the page flow, random application of styles you never created, and cross-reference truncation has got to be driving you crazy, so I invite you to read on, as well.

(If you're interested in a full workbook about these topics, see the Professional Techwriter workbook here. )

OpenOffice.org Professional Book Production Strengths

Styles rock. They have immense power for just all the things you'd expect from styles, as well as the sequence in which page styles (master pages in Frame) are used.

Styles in general. Styles are really well implemented in OpenOffice.org. You choose Format > Styles and Formatting, you pick what kind of style to create, and you go nuts. Use styles in a standard, consistent manner and you won't go wrong.

Page styles: To specify the layout such as type of headers and footers, margins, backgrounds, etc., you use page styles. You create them the same way you'd create a paragraph or character style. Page styles are pretty solid. You apply them by double-clicking the page style in the stylist, then switching from one page style to another with a manual break or one of two automatic approaches. You can also restart page numbering with all three ways.

Switching page styles: As mentioned, you can switch from one page style to another by inserting a manual break, or automatically. One way is to set up a paragraph style like Heading1 to always start at the top of a new page, with a particular page style. (Framemaker doesn't have this.)  For instance, if you always start a new section with the paragraph style Heading1 and use the page style FirstPage, then you can make that happen automatically and never think about applying page styles.

You can also set up a page style to be applied once, then automatically switch to another page style. Just as you might set up Heading1 to automatically switch to BodyText as the next paragraph style, you can set up FirstPage to automatically switch to LeftRight as the next page style.

Automatic PDF: If your department is on a budget, don't worry about purchasing high-priced copies of Adobe Distiller. You can make PDFs of your documents automatically. Just choose File > Export as PDF, name the file, and set your options.

Master documents: Master documents are the equivalent of master files and book files. They work. They're not slick and powerful, but they work. They also don't crash and corrupt the subdocuments. They're just a bit tricky; you have to do them the right way. You have to insert a Text Item component between each subdocument in order to be able to apply formatting to the subdocuments, but it's not hard to do. To create a master document, just choose File > New > Master Document and use the tools in the window to add files, TOCs, text items, etc.

Automatic captions: You can set up OpenOffice.org to automatically insert captions for all your graphics, tables, etc. They're numbered separately and you can have whatever word you want in front of the caption: Table, Object, Item, Illustration, etc. Choose Tools > Options > Writer > AutoCaption.

Tables of contents: Tables of contents are in generally pretty good. They're linked to the headings you set up in outline numbering (see Weaknesses) and tabs are included by default. I would say they're just as powerful as Frame but easier to set up. You have a lot of formatting power through styles.

Better drawing tools: It's not hard to beat the drawing tools in Framemaker, but OpenOffice.org does it by a mile. Use a frame (Insert > Frame) to group the items, or else just choose File > New > Drawing and make a separate diagram. Then copy and paste into a frame in Writer or export the drawing to a JPG or other format. If you do flow charts or diagrams, the connector line tools alone might be worth using Writer as your book production tool. (Or alternately use Draw to create diagrams that you export to GIF and import into Framemaker.)

OpenOffice.org Professional Book Production Weaknesses

Cross references: Generally, they're solid if not all that slick to implement. However, two issues. One, there's no way, as in Framemaker, to search for broken cross-references, though the cross reference does show up as an empty gray box. Sometimes it's not even an empty gray box, it looks fine. So that's a big issue.

Also, if you want to do cross-references between subdocuments in a master document, you can't select them from a list—you have to keep track of what they are and type the name of the reference in manually. AND the cross-reference doesn't show up correctly in the individual document, it's just a blank gray box. You can see it correctly only from the master document, which is read-only. Grr.

Outline numbering: Outline numbering is actually kind of a powerful tool, and not that tough to implement. Outline numbering is how you tell the program that ChapterTitle is your top-level paragraph heading style, Heading1 is the next level down, and so on. From that you get running headers and footers, automatic chapter numbering, etc. You can also have only one paragraph style at each level, so there goes the idea of having two paragraph styles, Heading1NewPage and Heading1.

Indexes: Indexes work, but they're a little weird and it takes a while to get used to how they work.

Chapter-page numbering: You can set up chapter-page numbering, such as 1-1, 1-2, 1-3, 2-1, and so on. You can apply chapter-page numbering to captions. You can have the chapter number in headers and footers. (Once you've set up outline numbering.) However, you can't have it show up correctly in the table of contents for the second level heading on down. Thus, you can either forego tables of contents, forego detailed tables of contents, or forego chapter-page numbering.

Running headers and footers: Running headers are easy, once you've set up outline numbering. Just go to the header or footer and choose Insert > Fields > Other, select the Document tab, select Type column, select the Chapter item, and choose what kind of information you want to insert. “Chapter” just means section, and you can specify what level section with the Layer field in the lower right corner.

There's just one problem. The running header or footer reflects the most recent heading. If you're writing about French Bread on page 1, and have a section title about Rye Bread halfway down the page on page 2, then the running header at the top of page 2 will be French Bread. It doesn't see anything on the current page, only what has already appeared in the document. If you had a running footer on page 2, it would show Rye Bread because by then Rye Bread would have appeared in the document.

This is an issue only with heading level 2 on down, since usually your top level heading will start at the top of a new page or document so quick switches aren't an issue. Therefore you can use only running headers for your top-level heading; you can use them for any levels but only in the footer, or you can use a separate page style for every chapter and type in all your headers and footers manually. The first and second are the best options.

Variables: Let's say you're putting together a huge document for a proposal, and the value like Contractor and Price and ContractorIDNumber appear several places throughout the book. Or you're doing a book for three different products and you want to be able to easily change the product name from BadgersRUs to MarmotMania. In Framemaker and in OpenOffice.org you can create variables to handle this. However, you can't share them across documents in OpenOffice.org, even if they're part of the same master document. You can't import them from one doc to another or from one doc to all other docs in a master document. You can do that in Framemaker.

In Conclusion...

Use styles. Use page styles. Take advantage of automatic page style application/switching. Set up outline numbering. Be flexible with your formatting requirements (notably with running headers and footers, and chapter-page numbering). Be very structured with the titles of your cross-references. Don't expect Framemaker. Do some test documents.

If all that sounds good, then OpenOffice.org could be a good tool for you and your group.

---

---

Comments

[Jean Hollis Weber]

I'm a technical writer who used MS Word for most of my work until I got the chance to switch to OOo. For the work I do, OOo does as good a job as Word but I find OOo easier to use; it suits what I do and how I do it.

In my work I often have to deal with large books containing chapters written by different people, so I use master documents a lot. In general, they work well but have some quirks that the Help doesn't adequately cover, and the quirks differ depending on exactly what you're trying to do and what other OOo features you're using (such as a complex mixture of custom page styles).

I've got a long description on my website of how I got master docs to work for me, and more info about them is given in the master docs chapter in the Writer Guide produced by OOoAuthors (http://oooauthors.org/ and available on the OOo Documentation Project's website, http://documentation.openoffice.org/. Alas, master docs have some problems if you use custom page styles and list styles; these bugs have been reported and I hope will be fixed before too long. But in general they work well, once you figure out just how to use some of the trickier features.

[Solveig]

Hi Jean,

You've got an amazing site with some excellent detail. I use Frame (never Word) to create my OpenOffice.org books and workbooks because of conditional text, existing content, and a host of other reasons, but you dived right in and took the bull by the master documents.

I encourage anyone using OpenOffice.org for heavy-duty publishing to look at Jean's site and other links referenced in her comments.

~ Solveig

[Paulo Eduardo Neves]

This is a somewhat old post, and I'll make a somewhat out of topic comment. Excuse me.

I love to use styles, but I'm unable to create beautiful ones. I can tweak already done styles, but I can't do one from scratch. What I really miss in OO are professional styles with the application. Word comes with some very good ones, and if I don't like them, I can download others from Internet or even buy. I've searched a lot but never found good styles for OO. Do you know if they exist?

[Solveig]

Hi Paulo,

I've been wanting to do a post on styles, and you've provided me with the push I needed. I'll post this coming week on how to create styles from scratch.

As for where to find nice styles, there are templates out there for Openoffice.org, notably at http://documentation.openoffice.org/Samples_Templates/

But remember that you can open any Microsoft Word document in OpenOffice.org. So if you have Microsoft Word templates or documents containing styles you like, just start OpenOffice.org, choose File > Open, find the file and open it. And there you go; the styles you like in the software you like.

Click in the text that you like and the paragraph style will be shown in the styles dropdown list at the top left of the work area, next to the font dropdown list. You can also choose Format > Styles and Formatting to see the list.

HTH--and come back to the blog to see the styles post.

~ Solveig

[Paulo Eduardo Neves]

Thanks for the great styles post. But my problem isn't really the technical side, but with the artistry one.

I'm not a designer, but I can easly adapt a style for my needs. I've been creating simple sites, like the one that announces my newborn son (http://www.leonardoneves.com.br ), with the web styles from Open Source Web Design (http://www.oswd.org ). It's easy to do professional looking pages.

What I really miss are good report styles to make professional documents. Today I just use Microsoft Word styles, but I feel like cheating. I also believe that finding word styles, copying, and importing them is a task too big for the casual user.

I just would love to see beaultiful document styles included with Open Office.

[Solveig]

Hi Paulo,

>> "But my problem isn't really the technical side, but with the artistry one. "

You might try the WorldLabel templates at
http://www.worldlabel.com/Pages/openoffice-template.htm

I agree, there's a big difference between just how to do it, and how to do it beautifully. I can do clean-looking templates but am not a designer. For now, we just have to keep an eye out for OOo templates, use Word templates if necessary, and maybe browbeat our designer friends into creating some beautiful OOo templates. ;>

~ Solveig

[Scott B]

There's a great article by Bryce Byfield called "Replacing FrameMaker with OpenOffice.org" that can be found here:
http://www.techwr-l.com/techwhirl/magazine/technical/replaceframewithwriter.html

[Xaprb]

I've used them. I have yet to see anything that can touch the combination of Vim and LaTeX. It excels no matter how you look at it. Name any feature you want about any word processor or similar GUI software, and it can do it, usually better (for me anyway). It may not be for everyone -- it may just be that I'm a programmer and I am already fluent with both. But for me, it's absolutely unbeatable.

[Solveig]

Hi Xaprb,

Those two features are very powerful. As you know, most people aren't as advanced and/or prefer a GUI. I have a friend who swears that LaTeX can do everything plus answer the door, sew you a nice suit, and cook dinner. I've researched enough to know it's almost true. ;>

[Solveig]

Thanks Scott--I had this article in the post originally, I think, but lost in in some bad HTML (one of the reasons for the repost).

Solveig

[Michael Shannon]

I've never used Framemaker, but people who have seem to love it.

OpenOffice is quite capable of "making books". I wrote, edited, and produced press-ready final .pdf files for my latest book using OO 2.0 beta.

Sure there were glitches and gotchas, but most were probably just user error.

Check it out if you'd like at http://www.smartguypress.com or the Amazon page here:http://www.amazon.com/gp/product/0977310507/sr=8-1/qid=1150204102/ref=pd_bbs_1/102-0418162-8304168?%5Fencoding=UTF8

BTW, great blog! I often refer folks with OO questions to it.

Thanks!
Michael Shannon
Author "Computer Secrets I Taught My Mom" ISBN 0-9773105-0-7
http://www.smartguypress.com

[Solveig Haugland]

Hi Michael,

I'm glad Writer works for you! Lots of people have a lot of success with it--for me, one thing is that I'm so used to the power and easy of Frame cross-references, and use them so extensively in many books. For regular ol' content, without the 1% of published docs that need the uber features, OOo rocks. (Esp with the PDF and the kickin' diagramming capabilities.)

Love your book title!

Solveig

[Kevin McLauchlan]

So, the original blog entry was written in 2006, and it's now 2008, and big, popular open-source projects move fast. Does the essential recommendation still stand, or is OOo now "close enough" that you'd use it for most techpubs work?

How about in the situation where FrameMaker is available (or the company would pay for it), but literally every other document in the company (that's not end-user instruction or reference) is created and endlessly fondled in Word?

Is it time, yet, to be an open-source hero?

Kevin

[Edith]

I would very much like to import .odt files into FrameMaker (started a new job and much prefer to work in Frame). I keep coming up with errors or Frame crashes. Would you have any tips about that?

thanks so much,
Edith

[Edith]

I would very much like to import .odt files into FrameMaker (started a new job and much prefer to work in Frame). I keep coming up with errors or Frame crashes. Would you have any tips about that?

thanks so much,
Edith

[Solveig]

Hi Edith,

Frame can't handle .odt, but if you export from OpenOffice.org to rtf, then you'll be able to open the file. Alternately try just copying and pasting, regular or Edit > Paste Special, and choose unformatted text.

[Aman Gopal Sureka]

Framemaker can print a rotated page with normal headers and footers, which means that the text can be in Landscape mode whereas the headers and footers are in Portrait mode, which i think ms-word (xp) can also. is it possible in ooo 3.0 ? or earlier versions ?

regards,
aman