I am currently porting the Linkage app from Windows to the Mac. It’s a fun project with many challenges and many annoyances. Designing a Mac-style sidebar to show the properties of selected items was fun. Trying to use a Mac-centric help system is terribly tricky.
For many years, Apple had a system where the developer created web pages for their app that were viewed in a help viewer app. This system is called “Help Books” or “Help Book”. A user clicked on the “My App Help” item in the Help menu, and the viewer would open and display their index.html page. The user can then navigate through the web pages using links on the index page. Apple has marked that system as “Deprecated,” which means developers should not use it. The thing is, Apple still uses it. They use it a lot. They use it in ways not even made available to developers (such as the built-in sidebar for their table of contents). The help viewer has been replaced with the Tips app, but it still works the same for a developer using the deprecated help book system.

Why would Apple deprecate this and keep using it for their app help pages?
Why is everyone starting to use web-based help that is only available online? It’s also hard to design web pages, so they show different content depending on the app version the user is using?
With the Windows Linkage app, I created a PDF file that opens in a browser or viewer when the user wants help. The PDF file and the original MS Word document are in source control. The PDF file is always appropriate for the version of the app it is installed with.

I’ll create a PDF viewing window in the Mac Linkage app and display a Mac-specific PDF file when the user wants to see the documentation. It’s not as cool as using help books, but also not mostly deprecated. If Apple would make the help system they use available to everyone, then that would make the whole system better. Maybe the move to forcing everyone online while they use apps, which is terrible, is making Apple think developers don’t care. That might be true in this world where every app becomes a licensed subscription and not something you can run without an internet connection. But that doesn’t make it good.