Moving a blog to Tinderbox: Troubleshooting Macs

I greatly enjoy writing this blog, as you may have guessed, but it always feels so profoundly ephemeral.

Despite maintaining tables of contents, various guides, and index pages, most articles here are read within a week or two of posting, then seem to vanish into obscurity. This is, of course, largely the result of search engines: a few articles reach the first page of hits, but most don’t, even though they may have been a labour of several days of love, sweat, and research.

It is tempting to suggest that articles about Macs and macOS are inherently ephemeral, but in fact many have surprisingly long lives before they are superceded or become incorrect. What I write today about macOS Sierra is likely to hold good for around six months, until we are getting to grips with macOS 10.13 in the autumn/fall, and even then there will be many who will stick with Sierra for longer.

This Tinderbox project is an attempt to turn this growing jumble of articles about troubleshooting Macs and macOS into something more coherent and systematic, thus more useful. It’s the exact reverse of what you’d expect: how to move content from this blog into a Tinderbox (and Storyspace) document. It’s also not about Tinderbox tricks – the features used are all straightforward, and commonplace – but the structuring and layout of complex information.


My starting point was the concatenated content of the most useful Mac articles here, in its simple WordPress marked-up text format. I thought about importing those articles direct into notes, but realised that the structure of the blog would then determine the structure of the notes. That is what I want to avoid.


So I stripped all the markup out, apart from links and embedded graphics. This forced me to look again at what I had written – over forty thousand words, for a start, and that’s just the hard core content – and how it would structure into notes.


Although there’s a lot of additional information which I could put into user attributes, I decided that I’d start without any, making prototypes merely to separate the different types of content, and differentiate them with colour.


I didn’t start with any Grand Plan, but added some of the most basic notes, and evolved my conventions as I went along. One of the earliest was the need to make links clear, and their types distinct. Here I like the ➜ heavy round-tipped rightwards arrow character as a signpost. But I also wanted to make it clear to the reader which links were internal, and which external. For this, Format / Style / Highlight is ideal, using yellow highlighting for internal, and blue for external.

Colouring text itself inevitably reduces its legibility, particularly for those with visual difficulties, and poses difficult choices to cater for those with impaired colour perception. Even if you cannot tell any colours apart, you can see highlighting quite clearly, and I particularly like the choice of colours in Tinderbox. Using highlighting does, unfortunately, have implications for production, which I’ll touch on below.


Writing for print and web publications is generally overloaded with graphics, in this case screenshots. A picture may on occasion be worth a thousand words, but many of the screenshots which adorn websites are trite and empty. I embrace Edward Tufte’s concept of the data-ink ratio, here as the data-pixel ratio perhaps.

What I am still thinking about (and invite your comments on) is using embedded scripts to open apps, etc., for the reader. For a complete novice these appear useful, but for my target audience I’m uncertain whether they would achieve much apart from irritation.


One of the great advantages of working with Tinderbox 7 is the ease with which you can insert Quick Links: two left brackets [[ and the initial letter of the name of the note which you want to link to, select it in the popup menu, and press Return (or double-click).

Because so much of my content is heavily interlinked, these are a great time-saver. For example, starting up in the different modes (Safe, Recovery, etc.) crops up time after time when describing how to investigate and resolve problems. Being able to add a Quick Link to a description of those procedures allows the reader to link out and refresh their mind as to just what to do.

Initially, I wondered whether a return link was desirable, but that is not feasible in most cases. Users will either have to use the Note / Go Back menu command, or work their way back in the Map View.


Most of the techniques articles have broken down into two or three interlinked notes, the first explaining what it does, the second detailing the technique, and sometimes a third providing more technical information. It has been valuable to let the content structure the notes, rather than setting out a formulaic approach, as each differs. In most cases, these originated in single articles here.


Finding the slickest way to style link anchors has been an interesting quest, and differs between internal and external links. An easy way out would have been to set Colored text links in the Text section of the Document Settings, but as I wanted coloured highlights rather than coloured text, that wouldn’t help.

For weblinks, added using the Make Web Link… command in the Note menu, I now insert my arrow using the macOS Characters panel, select the anchor text, and set its highlight.


I then copy the URL link, either from my original text or Safari, and invoke the Make Web Link… command. The anchor text is still selected, and the copied link automatically entered as the destination URL.

Internal links, created as Quick Links, are a little more fiddly. I insert the arrow, and its trailing space. I next bring up the menu of notes using [[ and the initial letter, and insert the link. I then have to select the anchor text before applying the highlight, which requires a bit of deftness with my Trackpad.

Perhaps a future version of Tinderbox will allow global styling of link anchors of each type using highlights, which would make this much simpler.

So far I have moved about a third of the content, over thirteen thousand words, and am encouraged by the document which is taking shape. You are most welcome to download a copy here: MacProblems1

This seems to work well in Tinderbox 7, Storyspace, and Storyspace Reader. As you must be running a Mac to be using any of those, I think you might find its contents of interest too.