The first steps in authoring your help book are identifying the topics your help must cover and designing a layout for presenting these topics. To this end, you may find it useful to create a topic outline. If the software product for which you are creating help already has existing documentation, you may be able to base your outline on this material. If you are creating a help book from scratch, there are a number of ways you can approach the outline. A few examples:
Html Help For Mac
Walk through the steps of the main task sequence in order. If you are writing help for a larger application, there may be several different task sequences a user would perform. For example, a productivity suite may have different task sequences for word processing, using spreadsheets, and creating presentations.
Compatibility Note: If your help book is used only on OS X v10.4 or later, use HTML 4.01 and use XHTML for the main page that contains the AppleTitle meta tag. Help Viewer references this file often and formatting it as XHTML improves performance. If your help book is also used on OS X v10.3 or earlier, however, use HTML 3.2 and do not use XHTML for the main page. If you use XHTML in that case, your help book will not be indexed properly.
Each help page should cover only one topic, which can be expressed in a few short paragraphs. As mentioned in the section Designing a Help Book, your help book may contain both overview and task information. Overview pages define terms and concepts important to your application or offer other general information that users may need to know to understand your software product. For example, the help book page shown in Figure 2-1 describes application menus.
Task pages, on the other hand, offer a step-by-step description of the actions the user must take to perform a common task in your software product. The help book page shown in Figure 2-2 describes the steps necessary to change the background of a Finder window.
The topic wrap-up. This includes any information the user may need in order to wrap up any task described in the page. It is also a good place to include tips, shortcuts, troubleshooting information, and links to related help topics. For example, the last paragraph shown in Figure 2-2 gives a hint the user might need in order to see a large picture in their Finder window.
In addition to topic pages, you may need to create navigation pages for your help book. Users should be able to find most of the information they need by searching and navigating through links in your topic pages. However, navigation pages, such as tables of content, allow users to browse your help book and navigate to topics they want to learn more about without having a particular search topic in mind. You may consider providing a table of contents at the following levels:
Including a table of contents on the title page, at the top level of your help book, allows the user to select a starting point within your help book. A title-page table of contents gets the user started in finding help, even if they do not quite know what they are looking for. Figure 2-3 shows the top-level table of contents for the Mail application.
As mentioned in Designing a Help Book, you should break complex topics with lengthy descriptions into smaller subtopics in order to keep each help topic short and focused. However, it may not be appropriate to include all of the subtopics directly in your main table of contents.
For an example of a help book to use as a starting point, see the files for Mail Help in /Applications/Mail.app/Contents/Resources/English.lproj/MailHelp/. (Note that you have to select Show Package Contents from the contextual menu to see the contents of the Mail.app bundle.)
Every help book must be enclosed in its own folder, which is in the Resources folder of the application bundle. The help book folder also contains a Resources folder. In the help books Resources folder, you put a folder for artwork that does not need to be localized and so is shared by all the localized versions of the help book. You then put as many localized versions of the help book as you need. At the top level of the localized help folder are the index file and the title page. The Application help bundle for the SurfWriter application would have the following structure:
There are many ways you can approach designing the title page for your help book. For example, the title page from Mac Help, the system help book, has a link to a help page that describes the new features in the current version of OS X, a link to a page that introduces the capabilities of the system, and offers a number of links to help pages answering common queries to get the reader started.
You should also include additional tags and metadata in your HTML help files to control how your help is indexed. Including this information improves the user experience of searching your help book by increasing the relevance of the results returned for searches of your help book and improving their appearance in Help Viewer. Controlling Indexing of Your Help describes how you can improve indexing and searching of your help book.
Compatibility Note: Starting with OS X v10.4, index files support several advanced features such as automatic creation of help-page abstracts. These index files have the suffix .helpindex. Help Viewer in OS X v10.3 and earlier, on the other hand, cannot read *.helpindex files. If you are writing help that must be compatible with OS X v10.3 and earlier, you cannot use UTF-8 character encoding and you must generate index files with the suffix idx (note the leading space) in addition to the *.helpindex files. The * idx index files do not support the new Help Viewer features.
Abstracts. An abstract is a brief summary of a help topic that is displayed when the user places the cursor over the topic in a list of search results. Users can determine whether they wish to learn more about the topic without actually loading the topic page.
Anchors. Anchors allow you to uniquely identify a topic or section within a page. Anchors help you provide quick access to help content; you can specify an anchor as the destination of a link or use the Apple Help API to search for and display the content identified by an anchor.
Finally, you can specify which content in your help book should be indexed, as described in Specifying What Is Indexed. By using these various elements in your help book, you can greatly improve the search results for your help book and make your help book more easily accessible from your application.
Keywords are a set of additional search terms for an HTML help page. When a user searches your help book for a term that is designated as a keyword for a topic page, Help Viewer returns that page as a search result, even though the term may not appear in the body of the page. Using keywords, you can specify a set of synonyms and common misspellings for topics covered in your help book.
Anchors allow you to uniquely identify topics in your help book. When a user follows a link to an anchor, Help Viewer loads the page containing the anchor. If your link includes the specific file containing the anchor (such as SurfScript.html#anchor1), Help Viewer scrolls to the anchor location (if it is not at the top of the page). For example, assume that SurfWriter has a simple scripting language called SurfScript. In the help page for SurfScript, you could specify a unique anchor for each SurfScript command, enabling Help Viewer to scroll directly to the desired text when the page loads.
You can also use anchors to load an anchored page from within your application by calling the the NSHelpManager method openHelpAnchor:inBook: or, for C applications, the Apple Help function AHLookupAnchor. To continue the example, SurfWriter could provide an online lookup function that loads the help page for a SurfScript command by calling the openHelpAnchor:inBook: method and passing the appropriate anchor name when a user Option-clicks a command name in a SurfScript document.
The NSAlert, SFChooseIdentityPanel, SFCertificatePanel classes provide help buttons for dialogs. To display such a help button and link it to an anchor in your help book, use the methods setShowsHelp: and setHelpAnchor: in those classes. See NSAlert Class Reference, SFChooseIdentityPanel Class Reference, and SFCertificatePanel Class Reference for details.
By default, each file in your help book is fully indexed. You can use the ROBOTS meta tag in the HTML header of a particular file to control how that file is indexed. The ROBOTS meta tag supports the values shown in Table 2-2.
Help Viewer can also download updated index files from a remote server. If you specified a remote URL in your help book's Info.plist file, Help Viewer contacts the server and checks for an index file at that location. If an index file is present, and if it is newer than the locally stored index, then Help Viewer downloads the file.
You can enrich the user experience of your help book by including additional resources such as animated tutorials, scripted tasks, and other multimedia content supported by Help Viewer. This section shows you how to:
The help:search URL allows you to create a link in your help book that, when clicked by the user, initiates a search for a particular term or phrase. This is particularly useful for linking to further information about subjects that appear in multiple help pages. Rather than link to each topic page, you can simply set up a search that will find all pages in your help book in which the subject appears. The syntax for initiating a Help Viewer search is as follows:
Using the help:anchor URL, you can create a link to any help book location identified by an anchor. It is often simpler to create links using anchors than to hardcode the path to the destination in the link, and it allows a link to be moved without having to update all the pages that point to it. The syntax for linking to an anchor location is as follows:
The bookID parameter is a string value identifying the help book in which Help Viewer should search for the anchor. If no help book is specified, Help Viewer searches all of the registered help books currently on the system. The following example creates a link to the topic on opening files in SurfWriter Help: 2ff7e9595c
Commenti