Welcome to session 125 about Apple Help. One of the blocks on my good, better, best diagram was titled Apple Help. And I was talking about how providing user assistance is really key. And what's interesting to note is that in the good, better, best diagram, providing user assistance with Apple Help was in the good scenario. It's one of the basic blocks of building blocks for providing a good user experience. It's one of the basic building blocks for Aqua. So a lot of times people think about help as sort of being the last thing they do for their application.

And really, it's one of the basic building blocks for your Mac OS X product. So it's great to see great attendance in the room here. I'd like to ask very quickly, just do a little impromptu survey here. How many of you are currently using Apple Help in your product, say on Mac OS 9 or something like that? Okay. How many of you are planning to or hoping to use Apple Help for your Mac OS X product? All right, fantastic.

So that's really great. So what we want to do in this session is we're going to have a little feedback attitude in the San Jose welcome room. And we want to talk to you about how easy it is to get Apple Help going and then move into some details about the APIs and all that sort of stuff. And then we've also got some really cool announcements. So I'd like to welcome Gordon Meyer on stage from our Instructional Products Group at Apple. And he'll walk you through some of the basics here.

Thanks for coming. It's good to see you all. I've been looking forward to this session all week. So let's get right to it. This is our agenda for today. We're going to start out talking a little bit about help philosophy, the things you can do in your help systems to make them good, to make them really hit the mark.

Then we're going to move into a discussion of the help viewer at Apple Help. We're going to look at all of its features, demonstrate them for you, and then we'll examine some of those features in detail so you can see what they bring to your help system and how to implement them.

Then we'll talk about authoring, how to create an Apple Help book. You'll see that you can take existing HTML content and move it into Apple Help in about five minutes. It's very easy to implement. But I know that all of you are not coming from a system where you already have HTML Help content.

You might have content in another format. So we'll talk about converting to Apple Help as well. And as John mentioned, we have a special announcement about that. So if you currently work in Quick Help or Win Help, be sure and stick around because there's a great new tool coming aboard.

After we talk about conversion, we'll cover everything you need to know from the programming side to hook up to the help system. The APIs, how to handle your help menu, how to put help buttons in dialogs, and so on. And you'll be pleased that there, too, using Apple Help is very simple.

Finally, we have time at the end for Q&A, so if there's something that we don't cover or you have questions, please be sure and come up to the mic. Because before you leave the room, we want to make sure you have everything you need to start implementing Apple Help and get your application shipping on 10. I was really pleased by the show of hands to see how many of you are moving to the system. We've had great adoption so far, and I'm anticipating a lot more now.

One too many. So let's begin with a little discussion about the philosophy of help. These are some ideas and principles that you might find useful as you create your help systems. They're things that we try and keep in mind as we create ours. Well, starting at the 10,000 foot level, what is it about help? What role does help play in an application? Well, it's one part of the documentation suite.

And what do I mean by a documentation suite? Well, I have a very broad view of that. You see, the documentation suite is everything you include with your product that helps users understand how to use it. You might have a printed manual, on-screen help certainly, a tutorial, a read me, your website. All of those things contribute to user experience and to the user education.

But so does the UI of the application. Help tags, error messages, dialogues, and the UI itself communicates to people how to use your app. So that's a pretty broad collection of things. So let's focus on help. I mean, every one of those has something that it brings to the party for helping users understand. But since we're here to talk about on-screen help, let's look at that specifically.

So what is the role of help? What does it provide that some of those other things don't? Well, for one thing, it's a companion to the computer. When you're using an on-screen help system, you know that your user has a computer in front of them and has your application. That isn't necessarily true for those other things I mentioned.

Why do people use help? Well, often it's a last resort for users. Now, not everybody uses help this way, but many do. And in fact, I do myself. I have a little story to illustrate this. I think you'll find that as you think about it, this might be how you use help as well.

So this was a couple weeks ago, and I just made a CD with iTunes. I burned some of my favorite songs on a CD, and I wanted to make a CD label. So I launched Illustrator, and I drew a couple of circles, figured out how big they needed to be, typed my song titles in and so on.

And on the label, I wanted a title for the CD, but I wanted the title to kind of curve around and match the roundness of the label. And I didn't know how to do that. I'd never taken text and set it on a curve before. So how did I approach the task? Well, I looked through all the menus, and I tried out the various tools, and tried to figure out how to do it.

I brought all my experience to bear with Illustrator to try and tackle this problem, and I failed. So my next step was to find somebody else who might know. I looked around me, among my colleagues, and asked a few questions. Hey, does anybody know how to do this? And it turns out they didn't know either.

So at that point, I had two choices. I could give up and decide, well, who cares if the text is curved? Or I could turn to the documentation, turn to the help, and try and find my answer, which is what I did. And I got in there, and I found my answer.

And it was a springboard for me. I was back working in Illustrator, completing the label the way I wanted to. And it was great. It was a very good help experience. and that's how many users come to help. So what can you do to your help system to optimize that kind of experience? It's an important role. There are a couple principles you can follow.

How do you optimize your help system for providing a great user experience? Well, you should consider thinking about a minimalist approach. Now, if you're an instructional design person, you know that minimalism is this entire school of thought and it has a lot of principles and some baggage associated with it as well. But I'm not going to go into all of that. There's really three principles that I have from that school of thought that I want to talk about.

And if you're not familiar with this, don't think of minimalism as meaning don't provide any help. That's not what it means at all. It sounds like it from the name, I know. So what you want to do is you want to focus on real-world tasks. People come to the help with a task in mind. In my case, it was curving text. I wasn't looking for help on using the Fit to Path tool.

You want to emphasize troubleshooting. Because people reach an impasse, right, they've tried to figure it out, they've asked for help, they couldn't, they come to the help with the documentation. There's a problem. They want to get on with their work. So include troubleshooting information in your help. Now separate troubleshooting sections are all fine and well and good, but if you can include troubleshooting information with your task instructions, it's even better. Because that's where people are likely to find them and likely to encounter the problem.

Another principle you can use is acknowledging prior experience. Now, I know all the authors out there do audience analysis, and they think about, you know, who am I writing for? Who's the person who's using this? Well, apply that principle down to the very task level. Think about the topic you're describing, the type of person who wants to do this.

For example, Someone who's coming to the help and looking for information about making a font italic, probably a novice user. They need a certain level of instruction. Someone who's coming to the help and looking for information on kerning pairs is probably an advanced user. They bring a lot to the table about font technology.

Acknowledge that as you provide instructions. We've all had the experience of turning to a help system and finding the information there either too basic or--

Another high-level principle you can use is to exploit the environment. The on-screen help system is on-screen and on the computer. It's not a printed book. You can do things in on-screen help that you couldn't dream of doing in print, such as providing automations and using animated graphics and so on.

Likewise related to books, it's kind of easy to find stuff in books. We know how to do that. You riffle through pages and you flip through things. On-screen help, you can't do that. You need to think about the structure and making things easy to find so people can locate information. It turns out that search is a really good way to do that. And we're going to talk about some of the search technology we have built into Apple Help to help you with that.

And finally, when you write your tasks, write for following along. Assume the user is following the instructions you're giving them. A book has to be very narrative in its nature, right? Because the reader might be on a train or on the beach, might not have a computer with them. And so when you look at a book, it needs to provide task instructions and kind of a narrative of what's happening on screen as you're doing these things to keep everything in context.

When you're on a computer, the user has probably come with a problem and is following your instructions along. If the UI speaks to the user and enforces conditions such as clicking OK or making sure a value has been specified and so on, let the user interface do that. Take advantage of those other pieces of the documentation suite that are available because you're on the computer. Help tags, for example, error messages and so on. It's not necessary to be as narrative in on-screen help as it is in a book.

So, yeah, I know what some of you are thinking. That's all well and good, but I've already written a help system, right? That's fine. There's still something you can do to make sure your help really hits the mark on Mac OS X. And to do that, you just need to provide a consistent help experience and adopt Apple Help. As John mentioned, it is the help system for the platform. We've worked hard to make sure the help system is optimized for delivering on-screen information like this. We've built in some special features that you're going to hear about today.

So that's one thing you can do to join the platform and make sure that the user has a consistent experience. You know, John mentioned in his talk yesterday at the Adopting Aqua guideline-- Adopting Aqua session that using custom controls that don't go with the rest of the UI can be confusing for people because they come to your app and they're like, oh, well, gee, what are these? Well, a similar situation happens with the help.

If you roll your own help solution and don't use the help viewer, when your customer comes and looks up the help, they're coming with a task in mind. But they open the help system and they see what you've created and then immediately their task becomes figuring that out instead of getting the answer to their question.

So I've talked about the features of Apple Help and how we try to optimize it for the on-screen environment. Let's take a look at it in action. This is Jess. Jessica is the tech lead for Apple Help and she's going to drive the demo for me. That way I don't have to point, click, talk and pace back and forth all at the same time.

So let's start with the Help Viewer. This is kind of the core of Apple Help. It's an HTML display application. You see it here on screen. There's a little opening animation we've included in Mac Help to welcome the user, invite them to type in a question. And that's actually a Flash movie playing in the Help right there.

Let's talk about the UI for a second. You see across the bottom we have some navigation controls and a status area. Across the top we have a very simple interface for searching. We have a large text field and a nice pulsing Ask button because we want to encourage people to search. So we've typed in a search string. Why don't we go ahead and click Ask and see what we get.

So that fast, the Help Viewer has searched through all of the content in Mac Help, some 300 pages or so, and has presented a relevancy-ranked list of results. Those are topics that are most relevant to what Jess typed in. Let's take a look at one of them. So this is, again, as a standard HTML page. You see the topic of the page. The yellow area there in the middle actually indicates actions. We're doing that in Mac Help.

Kind of echoes back to the color of help tags that you see throughout the interface. At the bottom, you see a couple of hypertext links. You can tell because they're blue underlined. But these are examples of something else we've built into the help, which is special handling for certain types of links.

And that one says Open System Preferences for Me. Why don't we click that? You'll see what happens is that System Preferences comes to the front. We've actually launched that from the help system. Behind the scenes there's an Apple script that's running from that href. So when the user clicks it, we run the script and tell System Preferences to come forward. This is a very simple example of automation, which we'll talk more about in a few minutes.

The other link, Tell Me More, does a pre-program search in the Help. You'll notice up at the top there, there's been a new search term entered. This is a way of gathering related topics without having the hard link to other pages. And again, we've searched all of the Help and presented the most relevant topics.

Let's look at the Help Center. So the Help Center here is unique as well. This represents all of the help books that are available on the system for the user to use. You can see Mac Help, iTunes Help, and one that I can't read. Why don't we take a look at that second one there. So it turns out that this is Japanese input method help. And of course, as a Mac OS 1080 program, the help viewer is completely international and can display whatever you need it to display.

So also installed on this machine is QuickTime. Let's take a look at that. So QuickTime help is rather unique. Now this page looks a lot like Mac help and this page is stored on the hard disk. But the rest of QuickTime help is on the Internet. It comes from servers at Apple.

And the help viewer has a very special feature built in and it's able to find a page even if it exists on the Internet instead of the local hard drive. So let's click a topic here and again this is going to do a search to come up with some related ones. We'll go into one of these.

and that page you're looking at just came from Apple's servers. See, we're able to do the search locally without connecting to the internet because our search index is stored locally. But this page came from the help servers. Now, of course, it happened really fast because we have a good network connection. If we had a slower connection, you'd see a little status message and a progress bar appear at the bottom of the help viewer window. So this allows us to continue to update the help after the product is shipped and make sure it's good content.

Also here is another link at the bottom. This one is go to a website. When we click that, we just pass it off to the web browser and load the URL. The help viewer, when it encounters a hyperlink that it doesn't process internally or does not refer to a help file, it passes it through the system to the appropriate handler.

Let's talk some more about searching. Let's look for something about sound here. Sound volume, that's a good choice. So again, we've searched the content. You can see all the stuff from QuickTime that's available. We didn't connect to the internet for that. But at the bottom of the page, you see there's a link that says Search All Help.

When we do that, the Help viewer searches all of the available help books on the system: Mac Help, iTunes, QuickTime, and so on. It's presenting the most relevant topics from all of those books. When you adopt Apple Help, your book will be listed in the Help Center as well and will be searched exactly the same way. That's it. Thanks. We'll see you in a few minutes, Jeff.

So we've talked about how help can be a benefit to users in providing a good, consistent user instruction experience on Mac OS X. But what are the benefits for you as authors and developers? Well, it's very easy to author. Apple's embracing open standards everywhere, as you're hearing throughout this conference.

And Help is another example. We use standard HTML. You can author Apple Help with any HTML authoring tool you choose. Anything from a Go Live or a Dreamweaver to BBEdit to Stickies to whatever you choose. Something on another platform. Whatever you use to author HTML today, you can continue to use with Apple Help.

It's also very easy to implement. These features we just saw in the Help Viewer, the internet connection, the searching, all of that is provided by the Help Viewer. There isn't anything special that you have to do as an author to enable those or make those work. And most importantly, it's one help solution for Mac OS X. Carbon, Cocoa, it doesn't matter. You can adopt it and deploy it with your application.

So let's look at the specs for the system. It renders HTML 3.2. That's without JavaScript or forms. Natively plays QuickTime movies. You saw an example of a Flash movie playing in there. But you can use any QuickTime media you want to. QuickTime supports over 200 different media formats-- JPEG, GIF.

Flash, MP3, you name it, basically QuickTime can play it and you can use it in your help system. And again, by saying we play QuickTime natively, I mean we do not use the QuickTime plugin. We use the Sherlock Engine for searching. That's how we get our fast searching and our relevancy ranking. You can launch AppleScript from a simple hyperlink. We'll get into the syntax of that later. And you can retrieve content from the internet.

The Help Center that you saw displays all the books that's available for the user. This is based on permissions. If the user does not have permission to launch your application, your help does not show up in the Help Center. That way users are insured of seeing reference material only for applications that they're actually able to use.

And if you're familiar with Apple Help from Mac OS 9 and Mac OS 8.5, where it started, you'll be pleased to know that you no longer have to store your help in one single location. It works seamlessly with help stored on the network or on the hard disk and, of course, on the internet.

So I'd like to talk a little bit more about this internet-based content because it's a very important feature of the Help Viewer, and it doesn't work like it does in a web browser. You might think it does, but it behaves differently, and let's look at it. So the help viewer prefers local content. It always looks locally first.

And by locally, I mean in your help folder with the rest of your materials. If it can't find it there, if that file is missing, then it will look in a cache folder. Every user has a help cache and the help cache contains files that were recently downloaded.

If it doesn't find them in the user's help cache, then it goes to your site and retrieves the page using HTTP. Now you tell us where you're going to put this content on the Internet. You give us the URL to pre-append to the location there when you index your content.

and once we do download a file, it's cached locally for three days. That way users can come back and look at it again without having to reconnect to the Internet, but it doesn't stick along so, you know, stay around so long that it's stale and in the meantime you may have updated what's on the Internet.

I have a little illustration here to demonstrate this. So the simplest scenario, a page is requested, it looks on the disk and it finds it, and so the help viewer opens the page. If it does not find it in your help folder, it looks in the cache, and if it finds it there, it opens it from the cache.

If it does not find it in the cache, it uses HTTP to go to your remote site, and it takes the page, downloads it, and puts it in the cache, and loads it from there. Now I keep saying page. That's not quite right, because this happens for every element that's on the page. If you have graphics, the same process is repeated. It will look locally, it will look in the cache, it will look on the Internet and retrieve it if necessary.

That way you can have a mix of local graphics with remote pages, or local pages with remote graphics, or all one or the other. It's very flexible in that regard. And as an author, you don't have to decide or even know where those pieces are going to reside. You make that choice at the very last minute when you ship your product.

And that's one of the key advantages of this. And you guys know what development cycles are, right? Your application engineers are creating their apps, coding madly, and your help team or your help person is following shortly behind, lagging, trying to catch up. At some point, the help has to freeze.

You have to ship the product. It goes off, it's done, but development can continue, and often does continue after that point. Bugs will be fixed or introduced. Features will change and so on. And that makes the help wrong. And having a help that's incomplete or incorrect isn't good for anyone.

So, when you get to that point where you need to freeze, you can take a snapshot and say, "What features of this product are likely to change?" take the topics that cover those features and put them on the internet. That allows you to be able to maintain them after the product is released or at least catch up right before it's released.

And as an author, you don't have to decide up until that very moment because the help viewer, as we've seen, looks in these places and finds the content. It's like a hunting dog. It'll sniff it out and find it in any of these locations. You don't need to make sure that all of your hrefs are pointing to specific folder names or specific sites. It handles figuring that out for you.

So how do you author Apple Help? Well, it's really easy. You start with HTML. Again, HTML You take your start page, the main page for your help book. That might be your table of contents, your quick clicks page as we saw in our demo. Whatever page you consider to be main for your help book. And you modify it.

You add one line. You add a meta tag. A meta tag is a standard HTML element. Put a meta tag of the type Apple title and the name of your help book. In this example, myapp.help. Add that to your one page. This is a standard element so other systems are going to ignore it. You can continue to deploy this information on other systems. systems, no problem.

And that's it. That's the only modification you have to make. You take your entire help folder and you drag and drop it on top of the Apple Help indexing tool. The indexing tool scans all of your content and creates a search index and puts it in the correct place in the folder for you. So you want to do this at the end, right? Because you want your help to be up to date. You want that search index to represent the latest content that you have in there.

When you index your content, this is also where you specify where that remote site's going to be if you're using Internet-based content. And this is also where you turn on anchor indexing. Now, we haven't talked about anchors yet, but we will in a moment. Just keep in mind that it's at index time when you turn this feature on or off to decide you're going to use it.

So you've created your help, where do you put it? Well, on Mac OS X, help resides inside your applications bundle. All the localized help can live there, just like all the other localized resources with Mac OS X. And this provides a nice drag-and-drop install of your application and all of its help files.

How do people get to your help? Well, three ways primarily. The first method of access, and the one you should definitely implement, is a help menu. At a help menu, we recommend a single item in there. In this case, it's Mail Help in this slide. It should obviously be your application's name, Help, with a command question mark as the keyboard shortcut. So why do we recommend one item? Well, you know, in user tests, it's interesting.

We've I've sat through many user tests at Apple, and we find that when people have a long, complicated help menu, especially when those items in the menu kind of all lead to the same place, right? They all open the help system and they go somewhere. I know as authors, it's painful to admit, but to a lot of people, it's all kind of the same.

If there's four items in the help menu, we'll often see people pick the wrong item five times in a row. Yeah, you stand back there behind the glass and say, no, how can you be doing this? But it's true. A nice, simple menu works great. And when people have questions, they just want to get to where they're going to get their answers.

You can also implement a Help button, which is the second graphic there. This is a great way to provide contextual help. And from the contextual menu as well, you can add a help item there. If you're going to do provide contextual help with a Help button or a contextual menu, you normally want to use an anchor to do so, and we'll talk about that.

So essentially, we've covered everything you need to do from the authoring side to get your help up and running. But what else can you do? If you have some extra time or you want to go that little extra step to provide a really good help experience, there are a few things you can do and take advantage of some of our advanced features.

and I are here today to talk about how to provide on-screen help for Mac OS users. In this session, we will talk about how to provide on-screen help for Mac OS users. We set up some user studies. Earlier in the study, we had someone do a task and they had to come to the help for information on it. We provided an automation that would actually do that task for them.

and 95%, maybe 99%, I think it was one person out of the group, chose to do the automation. Rather than doing the task themselves, they clicked, yeah, do it for me. I mean, come on, that's what computers are supposed to do, right? Do things for me. Well, later in the same study, we had another task, and in order to successfully complete that task, they had to undo what this automation had done for them earlier.

We wanted to see if people were going to become reliant upon that automation and go back to it or be stumped when confronted with having how do I undo this thing. And it turns out that nobody had any problems with that. Using the automation did not impede their ability to learn how to work with the system. And in talking with them after the study, they loved it. They wanted more of that type of thing. So this is a great opportunity to make your help stand out.

You can also improve search results. We talked earlier about how it can be difficult to find things in an on-screen help system. One of the best ways to find things is by searching. Come to help with a representation of your task, type in your question, and get a related list of topics. Now, to make that work, it's up to you as an author to provide keywords that are going to relate your tasks to real-world representations.

You can use the keyword meta tag for that. You can also use keywords to provide synonyms and misspellings. For example, we spell QuickTime a couple of ways in our help content usually to make sure that people can find it. Because believe it or not, people do want to spell it as two words, unusually.

You can also use the robots meta tag. This is a standard tag if you run a website and you're familiar with it. But this provides you with a way to omit a page from a search result. So that page will not come up when somebody searches for a term.

So why would you want to do that? Well, if you have a table of contents page or a Quick Clicks page, all of the words on that page are going to get indexed. And when a user types in those words, they'll see that as a result. And if they go to it, it doesn't really help them, right? It's just the table of contents. It's kind of being a tease. So you use robots to omit that page from searching. And that way, when people search, they get the pages with the real content on them.

Apple Abstract is another meta tag that we support. Add this to your content with the contents of this tag being a summary of the page. When that page is found by a search, that summary will appear underneath the topic title. This lets users get an idea of what's on that page, a little short paragraph describing what they're going to learn if they click on that. It makes search results a little bit more usable because they can decide. And if your content is on the Internet, it's even better because then they can decide and make a more educated choice when they go to download that page.

Anchor Lookup. An anchor is a standard HTML element. It's not visible to the user. It's contained in the HTML code. It's usually a short little phrase or a name such as printing 001. Anchors are how you provide access to specific pages of the help. As an author, you add this anchor to your page. You turn on anchor indexing when you index your content.

And then your application can display a page in the help simply by telling the help viewer to open this anchor name. The application doesn't know what page it's on. It doesn't have to know what folder it's in or any of its location. It just says, "Hey, help viewer, show me the page with printing 001 on it," and it'll happen.

Remote content, we've talked about this a little bit. This is a great way to help users and a great way to keep your content up to date, as I've said. If you're gonna implement it, here's a couple things to keep in mind. You want to optimize your pages for downloading. Now, a lot of help is text, and so they're small and they come down quickly.

But if you're using graphics, consider putting the graphics local so they don't have to be downloaded. Again, the Help Viewer will manage that for you. Or use QuickTime Reference Movies. And of course, in QuickTime, movies is what they call their file format. It can be a JPEG or a GIF. It doesn't have to be an animation.

But a reference movie is very small, just a couple of K. The Help Viewer will download that. And because it has the graphic that's referred to in the HTML, will display the entire page right away very quickly. Then QuickTime will see that it's a reference movie. And QuickTime will go out on the network and download the graphic that actually appears there.

Just a little tip for you. We've talked about searching. If you're going to use remote content, it's even more important to optimize for searching because you don't want people to hit the Internet too often. Try and limit the topics per page and make your topic titles very accurate.

What I mean by that, if you have a very long page with several topics on it and you do a search for it, only the title for that page shows up in the search results. If that title of the page doesn't reflect the rest of the information, they might not get that that's the page they should look at. So breaking that up into smaller chunks helps people find stuff, and it goes to optimizing for downloading as well.

These are some help commands you can download, excuse me, you can implement. I'm not going to talk about the HTML. I won't read it to you. That would be very painful for all of us. But these help commands are a special type of URL you can use in your content. You notice they all start with help colon, which is a special handler we've defined for the help viewer. And by using these commands, you can cause the help viewer to do things. You can tell it to go to the help center.

You can switch to another book. For example, if you want to take somebody to Mac Help, you can include a link in your content that says open Mac Help for me. When they click that, the help viewer will go find Mac Help. You can open to an anchor in a book. So if you want to refer to a specific page either within your own book or someone else's, you can refer to it by anchor without having to know its file name or location on the disk.

A couple more. You can perform a search. You saw this in the demo. Tell me more, our quick clicks that were in the demo. Those all perform a search within the help viewer. You can specify what book to search as well as the search term. and of course you can run an Apple script. Here's the syntax for that. It's a help:run script and you give the path to the Apple script that's included with your help content. You can also pass a parameter to that Apple script. So you can generalize your scripts and pass parameters to have them do specific things.

So we've covered what you can do if you're starting with a new help system, how to create a help system very quickly and get it into Mac OS X, how to take an existing HTML book, and Convertit to Mac OS X. But what if you're not starting with HTML? I know that many of you are coming from WinHelp or QuickHelp have existing help systems you want to get into this system.

Well, if you're coming from Apple Guide, there is a utility from our friends at GuideWorks. They're no longer with us, but before the company folded, they did make this utility available for all of us to use. Take your Apple Guide source, run it through this utility and it will just give you a very basic starting HTML framework for it. You can leverage some of the work you've done there.

It doesn't cover everything, but it'll get you started. If you're coming from WinHelp or QuickHelp, well, we have some really good news for you. As to the announcement we alluded to earlier, and to talk about that, I'm going to ask John to come back up on stage. And thank you for your attention.

So I'm going to be brief because I want to introduce somebody very quickly. But one of the things I want to say is that developer relations is one of our mandates is to make you successful on the platform. And one of the ways we want to do that is to eliminate some of the barriers that it takes to get your products onto the Macintosh because a lot of people are bringing products from other platforms. And the last thing we want to do is for you to have hurdles that you have to cross that are unique to Macintosh that aren't available, say, on another platform or don't exist on another platform.

And one of those barriers currently was a lot of people are coming from Windows to Mac OS X and they have content on Windows in WinHelp format and they needed to get that over to Apple Help. And so I want to introduce somebody that we've begun to work with, Jack Minsky from Software Mac Kiev. and to talk about a tool that they've come up with working with us at Developer Relations. So Jack. JACK MAHER: Thank you, John.

So my name is Jack Minsky. I'm the president of Software McKiev. We are the world's largest conversion house moving stuff from Windows to Mac. Some of the titles you may have heard of that we moved, the World Book Multimedia Encyclopedia that we did for World Book IBM, Mavis Beacon Teaches Typing. We did SimCity 3000, KidPix Deluxe, SPS S10, and a couple of hundred others.

More recently, we've been moving things to Mac OS X, and we've also done some WebObjects projects, basically any Apple technologies that need to be implemented. As we were moving projects to Mac OS X, we discovered one of the things that shouldn't have been a long lead time item but turned out to be was moving things from something we use extensively called QuickHelp from Altura Software, which allowed us in doing these conversions to take basically the Windows Help file and move it over to run on the Mac.

very nicely. The problem with Quick Help is it doesn't have a Mac OS X version and probably isn't going to. And that meant launching Quick Help in the classic box, and that was something we didn't want to do. So we started painfully trying to take this RTF-based Windows help and move it over to an HTML base for Apple help.

And finding that took us two to three months per project and over the number of projects we were doing, that didn't make a lot of sense. So we set out to make a tool for ourselves in-house to be able to do that process on a rapid basis to automate it. And that tool is called Quicker Help.

We've made it into our first product that we're actually going to ship, one of our own tools. We've created lots of in-house tools. This is the first one through cooperation with Apple we've decided to make available in general to the developer community. It shortens the time literally from months to move your help over to a couple of days.

The utility itself, I'm going to show you right now, takes a couple of minutes to run, but then you still need to do some converting by hand. If you're starting from Win Help or Robo Help, you'd need to change all of the right mouse clicks to control clicks and those kind of things. It still has to be done by hand.

Of course, you'd have to replace screenshots. The basics of getting it from RTF Help, dividing it into those small chunks for HTML Help is all done automatically. What it does is it takes RTF Help, moves it to HTML Help, and again, Win Help and Quick Help files. I'd like to show it to you.

Quicker Help. Sorry. I like to see the bouncing shoe go. So I always want to put the dock up. OK, so the first thing we need to do is specify a project file. And we can do that either by using the Select button to find one, or of course, because this is Mac, we can use drag and drop. And I've identified here what's called an HPJ file.

Those of you who've made Quick Help before know this is the basic index file for the product.

and then that appears in my chooser here. And anytime I want to go back and retain that exact set of settings, whether it's the mapping of the fonts or the titles or whatever you've set up, you can have that exact one for help.

So we say OK, and we saved our preferences. And that's it. And we're ready to convert. Now let's give it a spin. I'm going to choose a place for the destination folder. I'm going to put it on the desktop so we can see it and create a new folder. And I'm going to call that one Jack's Help.

create that on the desktop, and it starts converting. This process is gonna take about another minute and a half, so give me a chance to tell you about a few of the other features. We did show this at the expo. Those of you who came by and helped by giving your comments, thank you for that.

One of the things that was requested that we've decided to add to the product is the ability to print out all the pages of help that you make instead of having to print them one at a time from the Apple Help Viewer. So that's an option that you'll be able to check a box in the preferences as well.

That's helpful if you're doing your own editing or you wanna give it to your QA group to try and check through the help and make sure that everything's okay. So here it goes doing the processing, and you can see going from RTF files, both text and graphics being created.

And at the end of the process, we'll be given a choice to, with two options. We can open up the folder that contains this help, so that you can go in and take a look at it, maybe start to do some editing right away. Or we can open up the final result, just take a look at it in Apple Help. I'm not going to open up the destination folder. We'll open Apple Help. And there it goes. We've got the help viewer jumping up and down here on the bottom. And there's the result, all converted from an RTF file into Apple Help.

And just to show you this is real, I have here in Quick Help the original file of this. You can see, for those of you who remember what Quick Help looks like, well, this is the opening Quick Help page. This is the opening Apple Help page. So you have a difference in environment there. We'll just drill down through a couple of these here so you can see that we've got essentially the same content. So these are exactly the same, or at least the same content. There you go. And that's what it does. Simple as that.

This is an almost final version because of a few things we wanted to add. And so we believe we'll have this all tied up and available even next week. We're going to be announcing distribution for this. Certainly it's going to be available for download from our website and I'll give you that contact information in a minute. And pricing is $5.95 for the SDK, the same price for those of you who have used Altura Quick Help as their SDK.

The difference being you don't have any kind of fees to pay for distribution of the Quick Help viewer. Apple Help is free. And if you'd like more information, please contact us. Write to me, [email protected]. Write that down. Or www.mckeeve.com on the web. We will be announcing some additional distribution next week. And we are going to stay at the end of the session. If you have any questions, please feel free and come up and chat with me and our engineers and be to answer whatever we can. Thank you.

So that's just an example of some of the tools that we're hoping to bring to the platform to help you move your help content across and even other stuff in other domains and other technologies on Mac OS X. If you have some specific tools that you're using that you think you'd love to have Apple produce or work with third-party developers to produce the conversion process or whatever, please contact me at the end of the session.

My contact info will be up on the slide. To continue with some of the lower-level stuff relative to Apple Help, I'd like to invite Jessica Kahn on stage. She's the tech lead for Apple Help at Apple, and she's going to walk you through some of the APIs on this stuff.

Hi everybody, thanks for coming to the session. Well, so far you've heard from Gordon and from Jack about what good on-screen help is, what the help viewer does to display it to the user, and how to create a help book. What I'm going to talk to you about is the help menu on Mac OS X, listing your book in the help center, which is that main table of contents in the help viewer, and accessing help from your application using menus, buttons, or contextual menus. And then we'll bring up John for Q&A. So Gordon mentioned before that the basic help menu on Mac OS X is what we recommend that you use and it's a single item, your application's name followed by the word help with the question mark key as the keyboard shortcut.

How do you get the basic help menu on Mac OS X? It's actually really easy. Some of you may remember from Mac OS 9 and before that you need to create an Apple Guide and that can be a little tricky. This, I think, is actually a lot easier. Basically what you do is, as Gordon mentioned, you bundle your application with its help content.

You define a couple of keys in your Info.plist, or for those of you who are familiar with localizing your application, those can be defined in the Info.plist.strings file as well in case you want to ship multiple languages of your help book. And then you define a couple of standard keys that you should be defining anyway if you're bundling your app, the bundle identifier and the bundle name.

I'll go into a little more detail about our special keys now. So that CFBundle help book folder key is basically, as you can see from the graphic hopefully, specifying the folder in which your help content is stored. That red circle is a little off, I'm not sure why, but it wasn't on my computer. Anyway, that's the help folder down in your app package. And this graphic displays your app once it's been built. That's where, if you had a global help book folder, it would be.

and the CFBundle help book name key is basically exactly the same as your Apple title. And so that's the key that's more likely to be localized, right? Because if you're shipping, say, a French language version of your help book, that title would probably be in French. And so that's the Info.plist key that you might define in your strings file rather than your main Info.plist.

Here's an example of the Info.plist. Basically, this just shows the four keys that you absolutely need to define for your help content to show up in the basic help menu. The CFBundle helpbook folder, as you can see, is a string value, my app help folder. The CFBundle helpbook name folder is--helpbook name key rather is also a string and that's your Apple title. Your bundle identifier is usually something that uniquely identifies your application to the system, something like com.yourcompanyname.yourappname. And your CFBundle name is sort of the user visible name of your application.

Okay, so let's step back for a moment. If you define those four keys in your plist, and you put your help folder down in your app bundle, and you launch your app, you're gonna get the basic help menu. And as much as we stress that the basic help menu is the easiest thing for users to use, we also understand that we need to be flexible for you guys, and that some of you are gonna want to have multiple help menu items doing different things. So an example of a custom help menu is bbeditshelp, and guess what, you can do it using Apple Help 2.

Here's what you need to do. Basically, you need to define an array value instead of a string value for that help book folder key, and that is a little clue to the system to say, hands off, don't touch my help menu. That means we're not creating a help menu for you at all. You need to use whatever standard menu managing APIs you use for Cocoa or Carbon to create your help menu, to add items, and then to handle those items. And you can use some of the Apple Help APIs that I'll be talking about shortly to handle those items.

So just again to stress how you would do this, you just, the change for the plist is just that you set an array value for CFBundle helpbook folder. And you can put your single string inside that array. Or if you want to ship multiple helpbooks, we allow that too. And so you would create an array and list your multiple helpbooks in there.

Right, so we've discussed how to have a basic help menu. We've discussed how to have a custom help menu. That's half the picture for accessing help from your application. You also need to make sure that your help is registered to appear in the Help Center. Without doing this, you're not going to be able to search. You're not going to be able to get to your remote content. You can't execute those Apple scripts that Gordon talked about and a number of other custom help features.

How do you do this? Well, it's pretty easy. You just call one API. We recommend that you call it each time your app launches because if the registration is already current, it's basically a no-op. You're not gonna spend a lot of time in that code. It takes an FS ref to the bundle of probably your application, but it could be any bundle in the system that contains help down inside of its resources.

It registers all books contained in that bundle as denoted by those special help list keys that we discussed for your info P list. And the good news is Cocoa Apps with just one help book get this for free. And so, as I'll demonstrate later, if you're a simple Cocoa application, you don't really have to do any work aside from storing your help content and setting your P list keys to have a basic help menu just work.

The caveats for this are that you should keep your Apple titles, those are the titles as they appear in the Help Center, as unique as possible to avoid user confusion. It's going to be a little bizarre for a user if they end up launching the Help Viewer and they see the main list of table of contents and there are things in there that are the same. They're not going to know where to go.

Also, the user needs to have launched your application once for your help to appear in the Help Center list. At first, I can tell that some of you might want to gasp at this limitation, but it's not as bad as it seems. Because the likelihood of the user wanting to get to Help Viewer application before they've ever even launched it is pretty slim. Okay, at this point, I'm gonna do a demo for you to show you that it really is that easy to have a basic help menu. Get rid of the stuff and launch Project Builder.

and PeeBee. Okay, so first I'm gonna show you, the nuances of making a basic help menu for a Carbon application and a Cocoa application are just slightly different, so I'm gonna show you each just to prove to you that it's simple for both of them. So let's create a new project in Project Builder. And let's make a Carbon application.

What are we going to call it? We're going to call it Carbon Demo. And then let's set its location. We're gonna put that down in my demo stuff, and I've already made a little folder in here that contains a help book. And so let's just choose that location and say finish.

and I are going to be talking about the project builder. The project builder is pretty nifty because it gives you a lot of stuff for free too. Basically at this point, if I just hit the build key, the build button, I've got a bare bones Carbon app that's already going to run for me.

So all I need to do to add my help to this is to click on the resources area of the project, go to the project menu and add my help files. which are stored in this folder. As you can see, this looks like a basic help book. So let's say we want to have this whole folder added. So let's highlight it and click Open.

and then here you want to be very careful, take note of this. Because we want to add the whole folder to the resources section of the project, we want to create a folder reference for the added folder. If we didn't do that, we'd end up adding separate files and that's not what we want. We want to think of the help book as a single resource, a single entity that gets copied around.

So there it is. Now inside there, I've got one HTML file that's, wow, that's a big font. One HTML file that's my main file for the book, and in here I've defined the Apple title, as Gordon suggested you need to do. So keep in mind, this is gonna be one of my plist key values. The other one is the actual folder itself that I've added to my app bundle.

So let's go set those key list P's. Rather, P list keys. Click on the Carbon Demo target, and you want to edit some target settings. So you go in here to Application Settings, and first, you make sure that you have a bundle identifier. So let's name this com.apple.CarbonDemo.

This doesn't really matter what our type and signature and stuff is. That can all be left at the default for this purpose. Past that, we actually want to click into the expert mode to add our new keys. So this is just a different view of the same stuff that you saw before.

And we're just going to add a new sort of top-level key here and call it CFBundleHelpBookFolder. Because we want the basic help menu for free, we're going to leave that as a string value. Whoops. And then it's going to move it for us so that it's hard to click in.

And we're going to name that the folder name, which I'll go back and show you in a moment because I can't look at that view right now. But the folder name, I believe, was CarbonDemoHelp. and past that we want to add one more sibling and that's the CFBundle Help Book name. That's your Apple title, remember. And for this example, I happen to make it the same name, but it doesn't have to be.

So we've added those things, and at this point, I think all we need to do is add a little snippet of code to our main source file. Now, this is only necessary for Carbon Apps, but don't be upset, it's not that bad. It's pretty simple, actually. so that you don't have to watch me struggle through writing code while I'm talking up here, I pre-prepared a little code snippet that we can plunk into there.

I'll try to show you this source in a way that you can see it in a moment as soon as I copy it into the main file. So we're just replacing that initialize with a snippet that also contains that initialize call. Okay, so let's expand this so that you guys can see that it's not that big a deal to register your book.

So basically, to register your help book, which is to get it into the Help Center, you get your main bundle, your app bundle, and then once you've got that, you get the bundles URL using CFBundle calls. Using that, you can get the FSRef and then you pass the FSRef to the AH register help book call.

Again, this is what puts your help book in the help center and this is what Cocoa Apps get for free that Carbon Apps need to do, but as you can see, it's only what, 12 lines of code or so. It's not that bad. All right, I think if the demagogues are with me, we're ready to build and run.

Let's make sure that Help Viewer isn't already running, because that would screw us up. It appears to not be running, which is good. So let's execute our little Carbon app. So here it comes. Now, it's got a help menu. And I promise you, there's no code in there to have started that help menu for you, to have given that to you. That's actually the high-level toolbox providing a free help menu. And it names it for you. And if we choose it, you'll see that it handles it for you as well.

and there we go, we're in my little help book that I created. So, you know, you spend a little time making a help book and then you spend, what was that, maybe five or ten minutes adding it to your project and you have a working help system in Apple Help on Mac OS X.

So now just to show you the nuances that are slightly different between Carbon and Cocoa, I'll do one more quickie to show you that the Cocoa app is actually even easier. So let's do a new project again. And this time, let's have it be a Cocoa application. Let's call it creatively, Cocoa Demo, and set its location similarly to the pre-prepared folder that I have.

Let's finish creating that. Alright, so, similarly, we're just gonna open up this resources section and add our help book. Cocoa Demo Help. make sure that that folder reference is chosen and then click Add. And then let's edit the target to define those keys that we need. So, again, we need to make sure we have a bundle identifier. and then we zip into expert mode and create our little custom help keys. Whoops, that always surprises me.

So, CFBundle Help Book Folder with Cocoa Demo Help, and then just to keep it simple, our Apple title or the book name was the same. So we've defined our keys, and now I think at this point we're ready to build. Oh, actually, let's just double check one thing.

I think, just to be really a little bit anal about this, let's make sure that our help menu is going to look right. This is the nuance for Cocoa. A basic Cocoa nib in the version of 10 that's shipping now already has a help menu in it, but you just want to go rename it.

So let's just call that Cocoa Demo Help and save that. And now let's build our app. and run our app. Here we go. We've got the help menu, Cocoa Demo Help. And without adding any code, you're going to see that Help Viewer is going to launch and display your help. So it's as simple as that.

and I'm glad the demo gods were smiling upon me, but I'm also glad to be back here talking to the slides again. Okay, so just to review what we've covered. We've talked about how you can get a help menu. We've talked about how you can get your book listed in the help center.

Those are the two key things you need to do to just have your basic help system working in Mac OS X. Now, I'll briefly just cover the Apple Help APIs, which are how you can hook up buttons and contextual menus. You can use these to access help content from all over your application. They're stored in the help framework, which is part of the Carbon Umbrella framework, but because they're a C API, they're usable by Cocoa Apps as well. They're available in CarbonLib 1.1 and later for CarbonLib applications.

There are five of them. We already talked about the first one. Two more go into a category of opening help viewer to a particular location, and two others are to perform lookups and searches. I have some sample code here. It might be a little hard to see, but I hope not.

The gist of the code is that this stuff is really easy. As you can see, all of those are one-liners. The first one is using ahgo2pages to open the help viewer to the help center. The second is opening to the developer help center, which is a special category of developer help content that we display in Mac OS X.

The third is using ahgo2pages, supplying the Apple title for your book and then not supplying the other optional parameters to take your book--to take your application, rather, open help viewer and go to the main page of your app's help. You can also use this with some optional parameters to get within your help book somewhere. Finally, you can use that API to get to any HTML or text file on disk, even if it's not inside of a help book.

You can also do lookups and searches. I'll briefly cover actually the last two on these slides. AHSearch is used, it's the programmatic way of doing a help:search URL. And basically it causes HelpViewer to open and perform a search. If you're familiar with the Apple Guide APIs, that's similar to the AG Open with Search API. The top one is the one that I really want to stress. That's AHLookupAnchor. And in my opinion, it is the most flexible API that we've presented and I hope you're going to use it.

As Gordon mentioned, it makes content authors free to reorganize the help content as they see fit without affecting the development of your application from the programming side. Be very careful if you're going to use this feature to turn on anchor indexing in the indexing tool. If you don't do that, it's not going to work.

Finally, for more information, you can see these URLs. I believe that you guys are gonna get a main URL at the end of this that is gonna contain all these, so don't worry about writing them down. But basically for your reference, there's an Apple help SDK. There's a new revision of the document providing user assistance with Apple help.

That's the canonical documentation for all of this stuff, and so look up stuff using that. Finally, grab the Carbonlib SDK, the latest version. That contains the help viewer for Carbonlib, which you'll need if you're a Carbonlib app and you wanna use our APIs. And also the newest help indexing tool, which is what contains the anchor indexing.

Who to contact. You can use these email addresses and these lists to get insider information about Apple Help. If you have any questions or you have any comments, we really do welcome them, and so please do get in touch using any of these methods. and at this point I'll bring John Galinzi back up to talk about our user experience roadmap and to start the Q&A.

Thanks, Jessica. So the interface builder session occurred. Application packaging occurred. Feedback forum for ACQA occurred. Carbon and those-- all of those occurred, but you can watch them on DVD. Speech Recognition is already done. Using Aqua and designing Aqua icons. Still to come. Great session. You need to come to that tomorrow. And then the feedback forum for the high-level toolbox if that's of interest to you.