Merging modern software development with electrons and metal
Random header image... Refresh for more!

Category — Technical Writing

My Choice For Writing Technical Manuals

I’ve been researching software that could be used for writing technical manuals.  My requirements include:

  • Doesn’t go crazy when I change formatting around (unlike MS Word)
  • Low cost or no cost, unless the benefits are overwhelming.
  • Reasonably good control over layout, but I don’t need super-precise control.
  • Easy to create Table Of Contents and cross-linked references.
  • Handles graphics, tables, and lists with aplomb.
  • Good, well written information (help, books,  blogs) available so I can quickly learn how to do what I want to do.
  • Easy to update text and improve text.
  • Easy to change formatting (for example, by using styles and updating the styles).
  • Good performance with long documents.  A lot of writers create one document per chapter, but I want to keep the whole manual in one document so it’s easier to create references, TOC, and such.

The basic types of programs available are:

  • Word processors, such as Word and Writer, that focus on the content and not on precise formatting.
  • DTP (desk top publishing) software such as Scribus, Adobe InDesign, and Quark Express that are really optimized for page layout; they typically don’t handle editing well, and often choke on long documents.
    • I took a long look at the open source Scribus program, but decided that this category wasn’t a good fit.  I expect the manual to be updated frequently, while precise layout simply isn’t needed.
  • Very structured software such as Framemaker and the TeX variants. These are more structured than I need, plus I want something more graphical than TeX.

My choice is LibreOffice Writer because:

  • Writer has better DTP capabilities than MS Word.  For example, it has styles for pages, characters, and frames, not just paragraphs.   A typography extension is available as are a couple of free, high quality fonts.
  • Writer is roughly comparable to Framemaker in capabilities (see here and here).
  • Writer is free, which is nice.
  • Writer doesn’t seem to go crazy when re-formatting; when I import my lengthy Word document and start changing styles, it does what I expect, unlike Word.  Performance on a 200 page document is acceptable.
  • There is some very good documentation available, including:

I plan to write an update when the manual is finished.

February 16, 2012   2 Comments

Microsoft Word 2010 for Technical Manuals

I’m in the process of slowly updating a technical manual; it’s currently in Microsoft Word, and was created by merging several earlier manuals.  The manual is over 200 pages long, and contains many photos, illustrations, and tables.

And I’m ready to dump Word.  I’ve used Word before, starting with Word 95, to write tech manuals but I’ve taken a lengthy break from tech writing.

I’m not a fan of the ribbon interface.  It’s like Apple stuff — it works great if you think as the designers do, but doesn’t work well if you think differently.  All those big icons and such make the supposedly more common stuff easier to find, but it makes the other features harder to find.  The ribbon interface makes it harder to explore and find out all of a program’s capabilities compared to browsing through menus.

I don’t like the current Word Q&A help system, either.  OK, I may be an old curmudgeon, since I haven’t like Word’s help since Word 95 — I think that was the last version that really tried to explain the basic concepts such as styles.

In my experience, Word can work pretty well if you start from scratch and lay out everything first, such as your styles.  If you have a Word document with inconsistent styles, lots of manual formatting, etc, and you’re trying to substantially modify its structure and appearance, watch out.

My current document’s problems include styles automatically changing when I try to apply them (and then changing the formatting of all the text tagged with that style to something I don’t like), tables flying apart or flipping when I delete some text or an object, and such.  I’ve quickly grown tired of re-doing the same thing over and over, so Word is out for lengthy technical documents.

February 15, 2012   2 Comments