November 2012
By Mirko Trepzik

Mirko Trepzik studied technical writing at the Karlsruhe University for Applied Sciences and has been working as a technical writer since 2004, presently for plant and mechanical engineering. Furthermore, he is also engaged in terminology and standardization. He has been working with Apple Macintosh since 1999 and offers technical writers support for Mac OS X, through the portal docxter.de among others.


mirko[at]docxter.de
www.docxter.de


 

This is a translation of a German article published in 'technische kommunikation', tekom's professional magazine for technical communication and information development. To read the original article click here.

Is Apple Help different?

The organization Apple has simplified the handling of computers and mobile telephones in many respects. Does this also apply to the Online Help integrated in the Apple operating system Mac OS X? Little is known about how the Help is created.

Apple’s operating system for desktop computers – the Mac OS X – came more and more into the limelight with the successful sale of the iPod, iPhone and iPad. The related Online Help format Apple Help is not actively supported by the customary Help author systems under Windows. A few special HTML elements allow at least the preparation of such a Help even without special author systems or the operating system Mac OS X. We would search in vain for the Help format of Apple next to CHM, HLP or HTML Help in the usual content management systems or writing system such as RoboHelp, Flare or AuthorIT.

Apple Help is a rather simple HTML based Online Help, which does not represent any great hindrances. Since only few special HTML-elements are required, already existing HTML based Online Help Systems can be made Mac-compatible without much effort. Apple Help is based on the HTML 4.1 industry standard. The author of the Help can therefore freely decide which editor he will use for creating the Help files. Thus any xml writing system can be used for the creation with corresponding style sheets. Any Internet browser suffices to review and test the basic functions and content of the Help pages.

That’s all?

All files required for an Online Help are located in a separate folder, the so-called Help Book. Although Apple recommends a certain folder structure, it leaves the file organization within such a Help Book to the author of the Help. For the simplest Mac Online Help all that is missing now is a simply prepared start page. This is the only element that must correspond to the XHTML 1.1 standard.

Unlike all other files, the start page in the Help Book must be at the highest level. The program “Help Viewer”, a special Help browser, which later presents the Online Help under Mac OS X, identifies the start page from Apples own Meta tag “AppleTitle” in the header of the HTML-file.

<meta name="AppleTitle" content="Program Help" />


The value of the content-attribute must be identical to the title of the Help Book. A help file could look like the following in the simplest case:


To link the Help Book with the actual software, the entire file contents must be processed under Mac OS X with the help of an indexing program provided free of charge by Apple and an index file must be created. It is possible for the user to conduct a comfortable full text search only after this. The Help Book created in this manner must then just be copied or moved to the corresponding subfolder of the respective software – and that’s it. More on that in figure 1.


Figure 1: Online-Help in Microsoft Word
The graphics in this article are only available in German

There is more to it than that!

It functions as simple as that – and many software producers also keep it that simple. Often there is no Help available at all for small applications at first. There is a growing trend of providing the Help contents on one’s own website and just linking it from the software. This has some advantages, such as no dependence on the platform, a quick update of the contents, easy evaluation of user behavior and the opportunity for simple interaction with the users.

But where there is light, there is also darkness. Among the disadvantages of web-based solutions is the fact that an online connection is necessary, one must change to an Internet browser to read the Help contents and the influence on quick and high value search results is restricted.

However, the disadvantages are mitigated with the Apple Help being set up locally. Finally, most advantages of Internet based help can also be implemented.
The search for the right Help topic can be further simplified and accelerated for the user by adding more tags and elements in the HTML files. Some possibilities available are:

Keywords: Anyone knowing a little about HTML will quickly know the function of keywords. With keywords, the Help author has the option of giving his own search terms in addition to the words contained in the text. The use of keywords, e.g. for usual synonyms, typical wrong descriptions and words especially relevant for the Help topic is recommended.

<meta name="keywords" content="additional search terms" />

Description:
The description is similarly known from the HTML world. The description of the Help topic is displayed by the Help Viewer under the topic title in the hit list and thus forms a summary of the topic content. The user can thus identify what is included in a specific Help topic early on through the list of the search results without having to open the topic first.

<meta name="description" content=“description of the help topic” />

Segments: The so-called segments are a specialty of Apple Help. They are parts of an HTML file, which are treated like independent topics by the Help Viewer and indexing program, which is an advantage especially during a search. Each segment is considered as an independent HTML file and can have its own description and keywords. The Help author can thus reduce the number of files and consolidate several Help topics in an HTML file.



The segments are shown as separate hits during a search to which users can go directly.

If the Help author specifically wants to influence the search result, then he can achieve this by using so called ‘exact matches’. For the exact matches, he defines in a PLIST file (property list) which topic(s) should be displayed for a specific search term. Then, while searching, for e.g. “Print”, the user can be offered exactly the relevant topic in which the most important information on the topic can be found, thus considerably simplifying the selection – Figures 2 and 3.


Figure 2: Hit list in Help Viewer
The graphics in this article are only available in German



Figure 3: Hit list in Help menu
The graphics in this article are only available in German


It’s dynamic now

While Online Help has been static till now, Apple created a few opportunities for more dynamics. These include integrating videos, scripts and references to dynamically generated link lists, such as “Related topics”. The latter especially helps authors of Help, who need not update such link lists every time in case of additional topics, since the lists are only generated temporarily through the action of user.

Apart from HTML 4.1, the Help Viewer already mentioned above works with JavaScript and all images and videos qualified for the Web. If a corresponding plug-in is installed for Apple’s own Internet browser Safari, even the Flash format is not a problem. PHP can also come into play in topics that do not exist locally on the computer, but are loaded in the Help Viewer over the Internet. Thus comment functions and other database applications are also available. Different types of links and anchors are primarily responsible for the dynamics between the Help pages. These have been presented in the table “Links and anchors of Apple Help“.

Links and anchors of Apple Help

<a href="topic.html">Topic Page</a>
Reference to an existing HTML-page within the Help Book.

<a ref="http://www.apple.com/support/safari" target="_helpViewer">Support Website</a>
Reference to an external Internet page that is to be loaded in the Help Viewer.

<a href="/SurfScriptPlayer">
Calling one of programs installed  on the user’s computer.

<a href=x-help-script://com.mycompany.surfwriter.help/scrpt/ScriptName?optional_string_parameter>
Calling an AppleScripts, similar to a batch file, for automatically starting and controlling locally installed programs with simultaneous transfer of different  parameters.

<a href="help:anchor=anchor_name bookID=com.mycompany.myapp.help">
Reference to a  jump label within the current Help Book.

<a href="help:search='search_term' bookID=com.mycompany.myapp.help">
Starting a search generated at runtime for a pre-defined term in a defined Help Book.

<a href="help:topic_list=almh10090 bookID=Mac Help template=sty/genlist.html stylesheet=sty/genlist_style.css Other=Accounts preferences">Accounts preferences</a>
Calling a link list generated at runtime from topics, which contain a defined anchor. The concerned Help Book as well the corresponding layout information for presentation of the link list is given.

<a href="help:openbook=com.mycompany.myapp.help">
Calling a specific Help Book installed on the user’s computer.

 

Please enter

The user gets access to the Help topics in different ways. The most frequent is the standard Help menu within the respective program. The search field integrated there draws the first hits even without opening the Online Help itself. The access is context sensitive and through Help buttons that are often found in the setting windows or dialogue windows. A very rare type is the third variant, the keyboard command “Command + ?”. Not like in the Windows-world where usually F1 is used.

Except for the simple presentation of HTML pages, the Help Viewer has very few extended functions. Along with the interpretation of the addressed special links and tags it only permits a search within topics and Help Books. Accessing other Help books is also possible, as is printing topics and setting and managing bookmarks – Figure 4.


Figure 4: Help Viewer under Mac OS X
The graphics in this article are only available in German



If a server with other topic contents was mentioned while indexing, Help Viewer – while starting – checks whether more current content is available and prefers it to the locally installed content. If there is no Internet connection, only the present Help files are available. A stop word list can also be applied during indexing, which excludes general words like articles or pronouns from the index – Figure 5.


Figure 5: Indexer under Mac OS X


Grateful users

Unlike other Help formats, Apple Help is a rather simple format, which nevertheless has some special features. Since they are all optional, the Help author is free to decide how well he considers the target group of Mac users.
The advantages of Apple Help are numerous:

  • better acceptance by the users due to familiar functions
  • large influence on the search results through descriptions, keywords, stop word lists and exact matches
  • complete integration of many media and scripts qualified for the Web
  • interactive control of programs from the Help
  • Updates and extensions of Online Help over the Internet
  • simple customization of already existing HTML pages to the Apple Help format

Even chapter based Online Help with dynamic content lists is possible with Apple Help [1].

Even if the final completion of the Help must take place under Mac OS X, a large part of the work can also be completed on a Windows computer. Except for the few special HTML elements required by the Help Viewer for controlling the Help, the rest of the Online Help is familiar terrain and should not make any Help author face unsolvable tasks. The Mac users will however thank him, since even Mac software often cannot be operated intuitively.

Links to references

[1]    Beschreibungen von Apple zum Thema Hilfe-Verfahren