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

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.

2 comments

1 Karen { 12.09.14 at 12:27 pm }

I’ve been trying to determine the best software tool for writing a technical manual–your post is exactly what I’ve been looking for. How did it work out using LibreOffice Writer? My biggest concerns are 1) formatting (esp. of images) doesn’t go crazy when content is modified, 2) easy-to-edit by new users.

2 Tony { 12.09.14 at 4:20 pm }

I’ve since managed to pass off manual writing to someone else 🙂 but overall LO Write did OK. I occasionally had to do things like send pictures to the back so you could see the graphic annotations, and fiddle a bit with the layout after edits, but overall it was much better than Word. Writer isn’t going to match a DTP program like Scribus for precise position, and if you want everything to look nice, you’ll need to check things over after making major changes.

Both Word and Writer seem to do better if you’re starting from scratch, instead of trying to re-format a bunch of text from several different sources (which is what I was stuck doing).

LO Writer does work much better when you set up styles for everything; I’d definitely recommend budgeting some time for experimenting with it and trying to understand its philosophy (in geek terms, “try to grok Writer”). For clients, it’d probably be best to setup some templates and styles (and you can assign various styles and such to function keys or control keys) and provide a guide.

My guess is that LO Writer isn’t perfect, but overall it’s probably as good as anything else (considering capabilities, support, ease of use, and cost) and worth a try.

Leave a Comment