Often the most time-consuming phase of writing software isn’t the coding itself, nor testing and debugging, but documenting an app for its users. On a good day, I can put together the first version of a basic utility like XProCheck, or a new log module for Mints, in a few hours. Testing and debugging is inevitably more variable, but writing documentation can take longer than both of those put together.

One problem is the standard Help system, which is neither well-supported by authoring tools, nor does it work at all well. I started using Help Crafter, which provides a friendly interface and full WYSIWYG, but the steady decline in performance of the macOS Help system has made traditional Help books embarrassing. Even in Apple’s own apps, they can take more than ten seconds to open, sometimes fail altogether, and when they eventually decide to cooperate, the Help window gets put to the back, and is lost among everything else. That is sometimes so bad as to give the impression that the Help book hasn’t opened at all, and I’ve had several users ask me why it fails.

I also like to provide a separate PDF version for reference. Although Help Crafter does generate PDF, it’s not as good as that created in my favourite document editor, Nisus Writer Pro. A few years ago, I decided to abandon normal Help books and make my own using PDF generated from Nisus, and that’s what most of my apps use.

Now, my problem is that no one seems to look at them.

This isn’t personal. If you’ve asked questions here, or by email, and I’ve referred you to an app’s documentation, I’m not getting at you, but trying to understand why my documentation doesn’t seem to be fit for purpose.

I was quite proud of the additions I made to SilentKnight’s Help Reference explaining its checks on XProtect Remediator scans. Yet I’ve been asked a succession of questions about this new feature by several users.

The great thing about these PDF help files is support for high-quality screenshots, good layout, and hyperlinks to help you use an app from the start. This example is taken from the early pages of the Help book for Ulbow.

In many cases, I include detailed information that you won’t find anywhere outside this blog. Here, in Signet’s Help book, is a concise guide to the most common error codes resulting from problems in validating code signatures. SilentKnight’s Help reference tells you all the tricks that it uses to get its information, and to list and install updates.

I’m well aware of strategies used by some apps to persuade you to read their documentation. I don’t like splash screens trying to lure me to read brief introductions, or listing help resources. I’m that guy who looks for the checkbox allowing me to skip that interruption whenever I open that app, and I suspect many of you are the same. I’d be interested to know how successful such splash screens are in their aims, or whether everyone disables them on first run.

As none of my apps tell me what you do with them – indeed, I don’t have a clue how many use any of them, because I don’t believe in collecting any information from you – I don’t know whether anyone looks at their documentation. Do you ever refer to it? Is it helpful? How easy is it to navigate using its hyperlinks? Is it well structured? Or am I wasting my time?

More to the point: given that many don’t appear to look at app help resources, what would you prefer instead? I’m afraid that I refuse to post a series of YouTube tutorials, as that’s a medium that I particularly hate. Help and documentation can’t be delivered successfully in a serial medium like video, as each user needs to be able to tailor their own path through the information, and proceed at their own pace. However attractive a talking head might appear, it’s the wrong thing for documentation.

Maybe we’re witnessing the death of traditional documentation, but I’ve not seen anything that can replace it. Although I’ve repeatedly called on Apple to improve its documentation, I use what it provides extensively. For almost every topic, my first searches start with the words apple support and apple developer, and very often top hits do answer my question. Rather than expect you to search here for tutorial and other articles about my apps, I link to them on their product pages. Although I may not know how many use my apps, I do know how often those product pages are viewed, and they appear popular.

While I’m happy to continue to document each of my apps in detail, if that doesn’t reduce the time I spend answering your questions, then I’m not sure that documentation is a wise investment of my time. What should I do?