Re: Help with Help
Re: Help with Help
- Subject: Re: Help with Help
- From: Jakob Egger <email@hidden>
- Date: Wed, 07 May 2014 15:44:20 +0200
I'd strongly recommend against using Apple's Help Book application. There are a few problems with Apple Help:
Problems with Help Books
====================
First of all, they are poorly documented. It is extremely difficult to structure them in the right way. You can't use HTML5, you have to use some special XHTML doctype. It took me weeks to find the right tags / anchors and all the implicit requirements to get it working.
Once you get them working, they might fail mysteriously. Sometimes Help Viewer won't find your Help Book. Sometimes it will take 30 seconds or longer until the Help Book is displayed, without any sensible feedback to the user. Sometimes old versions of your Help Book will be displayed.
Searching Help Books is slow. Again, no feedback, so your users will think there are no results, when in reality Help Viewer is still indexing your help book.
Additionally, the erratic behaviour seemed to change with every major version of OS X.
Finally, when I contacted Apple Developer Technical Support, they told me that they don't offer support for Help Books.
Alternatives
=========
The solution I went with was to use a simple web view that displays normal HTML pages. A plain window with three toolbar items: back / forward / index. Additionally, I provide the documentation for the latest version on my website.
The HTML in the app and on the website is slightly different, I use PHP to generate the HTML.
A more modern approach would probably be to use a static site generator like Jekyll, which would allow you to use templates, write in Markdown, etc.
Best wishes,
Jakob
Am 29.04.2014 um 19:52 schrieb Gordon Apple <email@hidden>:
> We would like to get a recommendation on the best way to generate a help
> system for a fairly complex application. We started by using a simple web
> view and created about 120 screens in BBEdit, mostly drill-down outlines.
> Unfortunately, this has been proven to be difficult to maintain. We¹ve
> looked into web generators like RapidWeaver, Freeway, and even Dreamweaver,
> but all of these have been described as ³roach motels² where you enter but
> can never leave.
>
> We would like to have both local and web-based or web-updated content and
> have contextual help. This all brings us to Apple¹s ³Help Book², which seems
> to have been around forever and presents its own learning curve. So the
> question is: Is this the way to go? It it still current? What are the
> experiences in using it?
>
> _______________________________________________
>
> Cocoa-dev mailing list (email@hidden)
>
> Please do not post admin requests or moderator comments to the list.
> Contact the moderators at cocoa-dev-admins(at)lists.apple.com
>
> Help/Unsubscribe/Update your Subscription:
>
> This email sent to email@hidden
_______________________________________________
Cocoa-dev mailing list (email@hidden)
Please do not post admin requests or moderator comments to the list.
Contact the moderators at cocoa-dev-admins(at)lists.apple.com
Help/Unsubscribe/Update your Subscription:
This email sent to email@hidden