Rather Good Guides®

Documentation the way it ought to be.


What About?

As we wrote more and more pages in Microsoft Word we began to hear that whistling noise normally associated with a falling grand piano about to land on us. We had Serious Doubts whether Word 365 on the Mac was a viable choice for producing Rather Good Guides®,


We looked at using Word as just the word processor and tried to import a sample of the 300 or so pages we had already written manual into:

  1. Adobe InDesign.
  2. FrameMaker.
  3. QuarkXpress.


Nope. Nothing could handle the actual Word formatting. It would have meant starting over.


Furthermore, every new edition of a Rather Good Guide® would have to be laboriously laid out again, page-by-page. A definite non-starter.


Does exactly what its name suggests: it turns the page numbers in an index into hyperlinks to those pages. It takes a while to run (hint switch to Draft view), but then changes the index page numbers into the default Hyperlink style. You can find it here.

Give Jack M. Lyon a medal!

Word Is...

I have just spent the last year Word Wrangling -- that is, trying to publish the first in a series of Rather Good Guide® technical manuals using Microsoft Word on Mac. To say that it has been a challenge is British Understatement in the extreme. Words like frustrating, aggravating, nightmarish, and insomna-inducing are more on point than you can imagine.


Don't get me wrong -- well not totally wrong. Word is a pretty good word processing app for most people, most of the time. But if you really try and use some of its more advanced features, especially Word 365 for the Mac, then you're in for a rude surprise.


My original goal was to try and create an Adobe Acrobat PDF file that would be fully navigable with hundreds of cross-references, hyperlinks from the table of contents, table of figures, and the index. Generally speaking I was trying to construct a PDF that lived up to the concept of hypermedia first imagined by Ted Nelson when he worked on Project Xanadu, documented in Computer Lib/Dream Machines in 1974. We've come close to creating hypermedia for web pages, but not for PDFs -- I wanted fully crosslinked information with embedded audio and video so that a reader could navigate all around the document and could read, see, and hear all that was available. "Well," I thought, "it's been almost 55 years since this was first dreamed of, so how hard can it be?"


Fool! It's hard.


First of all, you are forced to face up to the fact that Word 365 on the Mac is the poor cousin of Word 365 on the PC. There are many things that work right on the PC that simply do not work on the Mac version. Just to name a few: Try exporting a Word document to a PDF on the Mac. It seems to work fine, but it strips out all of the hyperlinks from the PDF. You have to move the document to a PC version of Word and do the export from there to retain the hyperlinks.


Callouts on the Mac version of Word (those speech-balloons that you can use to point at things in a diagram or an image) do not work right on the Mac -- you can't edit their shape or if you try, you completely bugger up the margins of the existing callout -- and you cannot undo that -- you just have to delete the messy callout and insert a new one.


Worse yet, callouts don't automatically change their size as you add text so you are forced into a hellish nightmare of constantly checking to make sure that the last line of text is not partially cutoff by the callout inner margin.


But it gets worse...or should I say...it gets "Wordse." Word is excellent as a plain Word Processor. It works. You can create massive 600 page technical manuals (I did) and it will automagically create a table of contents, a table of figures, all with hyperlinks to the appropriate pages so you can zip from any table right to the correct page. You can even magically create an index by embedding appropriate index entries throughout the text. But the index doesn't have hyperlinks to the pages. What? That's perhaps the most useful way of being able to access a large document and Word cannot do it? Neither the Mac or PC version can do it.


Cross-referencing -- the insertion of a hyperlink in a Word document to another section in that same document -- uses an ugly, highly-repetitive, and user-vicious, dialog box that forces you to search for the "target" of the cross reference from the start of the headings every time -- and you cannot search for the specific text you want either. This works if you have maybe 20 or 30 headings, but when you have several hundred the time required to just insert the cross references will exceed your life-span. However, check the sidebar to the right. There is a third party product that solves the problem -- see CrossReferenceManager in the right side-bar.


Not being able to create an index with hyperlinks is a crime against humanity. Microsoft knows about this lacuna but seems to be distracted by offering other allegedly useful features to overcomplicate other aspects of Microsoft Teams (don't get me started). But again there is a third party solution. See the left side-bar for details of IndexLinker.





Using Word to produce technical manuals has problems with:

  1. Visual Basic for Applications  is badly buggy. Seriously.
  2. Exporting hyperlinks to PDF files.
  3. Callouts not adjusting size according to text in them.
  4. Callout shapes cannot be edited.
  5. Indexes can be generated but page numbers cannot be made into hyperlinks.
  6. The user interface for inserting cross references is brain dead.


[**TL;DR? Internet abbreviation for "Too Long; Didn't Read.]


Fortunately there is a Word (PC only, of course) product that allows you to insert cross references in a rational and humane way. You can find it here. If you plan on using cross references, you owe it to yourself to get it. It works and it works really well! Tell Lene Fredborg I sent you.

Copyright © 2020 Johnson-Laird Inc.