Starting software development is so much more fun than finishing off. You have an idea, you think you know how to tackle it, and the really exciting bit comes as you implement that in code, and get it working the first time.

It’s a bit like climbing: you’ve now reached the peak, and everywhere else is down. Testing your app out, finding stress conditions and exceptional cases to use in testing, getting the human interface both working and looking good, and finally documenting it really well – they’re all a bit like the climber’s descent: essential, demanding of great care, and sadly all too often when fatal accidents happen.

A glance at the Downloads page here a couple of weeks ago shocked me into realising that almost everything listed there was unfinished, still in beta. It didn’t affect me a great deal, as most of the apps there were originally developed because I wanted them for my personal use, so those betas were just fine. But it wasn’t at all helpful to anyone else. If I was going to continue to offer a tool, then the least that I could do was to bring it to a stable, functional, and decently-documented first release.

Over the last week, and into coming weeks too, I’m having a big push to change all those betas into release products.

In most cases, there have been outstanding little coding tasks – tweaks to the interface, putting slower tasks into the background so the spinning beachball doesn’t annoy or confuse, and the like. There are usually some Tooltips to add, and minor rearrangements to dialogs and other windows. But the biggest and most daunting prospect every time is writing the Help book.

I know that a lot of developers have abandoned the regular Help book in favour of a remote support site, or alternative formats such as PDF. Like so much of macOS, Help books and the Help Viewer are quite ancient, were marvellous at the time, but have been left to fester like yesterday’s (or rather 2008’s) pizza. High Sierra 10.13.4 has addressed some of its problems, making it more responsive and coping better with multiple versions of apps, for example.

The biggest remaining issue is authoring tools for Help books. I continue to use Putercraft’s Help Crafter, which I like a great deal, and it does the job very well too. But as far as I can see, it is the only tool of its kind available on the App Store or anywhere else.

Help Crafter is fine for creating Help books in a particular style, but it doesn’t offer any more than that one style. It’s also fine for creating single Help books for individual apps, but where you have common content across two or more apps, all you can do is copy and paste between their Help books. It’s an app, rather than a full-blown authoring environment.

Other developers have pointed out how frequently Apple has changed the Help system, requiring existing Help books to be modified in order to keep pace. It worries me that a single app from a single developer is all I have to rely on. What if macOS 10.14 breaks many existing Help books, and Help Crafter isn’t updated to cope? Should I just go for PDFs, which are supported by a very wide range of authoring tools, and shouldn’t ever become orphaned?

It seems that it’s now quite common for apps in the App Store not to have any Help book, or what they provide is rudimentary in the extreme. For simple one-trick ponies, that often isn’t a problem. But as App Store apps don’t ship with separate documentation, unless it’s wrapped up in the app bundle, they have very limited scope for proper help outside of a Help book of some sort. And how many app descriptions can you recall that include details of the help they provide?

Call me old-fashioned, but you can’t ship the release version of an app unless you deliver it with proper documentation. Not just a link to a few scrappy cobbled-together pages on your support website, but something of which you and your users can feel proud. I hope my own efforts meet that expectation.