---
title: WWDC2003 Session 408
framework: wwdc
role: article
path: wwdc/wwdc2003-408
---

# WWDC2003 Session 408

## Transcript

Kind: captions Language: en my name is Gordon Dwyre I work in out products group instructional products makes the on between help and and the printed manuals that come with apple products and in this session we're going to be talking about Apple help you know what's five years ago at WWDC that apple health was first introduced for back in mac OS 85 it was so i see some people who have been with us all along from the very beginning developing for it thank you today we're going to have some changes to announce that I think you'll be very pleased about you certainly been very patient waiting for them and I see a lot of new faces too so I hope you're here to find out what apple health is all about if you're waiting on the fence to see if we're serious about an HTML health system well you can keep waiting another five years or come on in the water's fine we'll talk about how you actually generate your content you'll see how easy it is to hook things up now I'm the kind of guy who likes to eat dessert first so we're going to start with a demo and the demo is where all the exciting stuff is and so we'll do that first and in fact there's so many changes to Apple help the hood in the last year that you might say my goodness you've changed everything well we changed a lot but you don't have to worry if you've been developing for Apple help for a while your stuff still works so in that sense we've changed nothing for men we're going to talk about how to develop for Apple help you'll see how simple and easy it is to get your book in the help system and running under the system and then finally we're going to wrap up with some tips about how to optimize your health system and how to take advantage of some of the unique features that Apple help present so let you in on a secret we're actually going to finish early today we don't have the full time allotted that's not because there isn't a lot to cover because there is and there's lots of things to say you'll get to listen to me blab for several minutes but it's really a short presentation because Apple help is so simple when straightforward we've worked really hard to make sure that you can deploy your help content quickly and easily but enough of that let's get to the demo great so to get started here I'm going to open up to the help viewer this is Panther that you all have in your registration kit Wow look at that that was fast wasn't it in fact I almost don't believe it wasn't running let's try it again about two and a half seconds yeah sure you know I saw you in the back of the room I said I was going to open up the help and you got up to go to jamba juice figured you could make it back in time before I was ready to talk again it's much faster in Panther we've done a lot of things to really improve it and I know that was a much needed improvement we certainly are aware of that and have heard it loud and clear from all of you but that's not all you'll notice as I mouse over this sample page here we're getting some text decoration and that's being accomplished the links are underlining that's being accomplished with a CSS the style sheet here that specifies this text decoration so he'll viewer now works with cascading style sheets and HTML 4 in fact it works so well with web standards that you can now go out to the internet and find a site that generates content for you creates HTML templates and use them yourself just to prove the point I went out and found such a site and asked it to create a couple of a dummy help pages for me now I don't necessarily recommend these a great help layout but they do serve a really interesting point and this is an HTML 4 with a style sheet and as I click these buttons here you'll notice that I getting some nice roll over effects and lots of colors are changing and content is rearranging itself on the page and that's all accomplished through CSS with the same body text appearing in each one of these styles this turns out to be really powerful not just for web development book but for health development too because the more you can do two separate style and decoration from the content the easier time you have developing your content so finally you can do that with help you er another thing we support is JavaScript so this is a very simple javascript demonstration downloaded from another website and just dropped in to help viewer you'll notice of the time is incrementing as I talk here there are lots of things you can do with javascript in the help and luckily they all just seem to work i'll stop the timer there and start it this is a go back button isn't a hard link to the previous page but rather a javascript function that tells the viewer to go back in its history to go back in time and that works and help you were just as you expected to so finally web standard support it helps you or for panther let's go back to slide so how did we accomplish this well it's no secret if you've read your program or have been attending other sessions help viewer is now a client of WebKit we're using the safari technology to support all of our HTML display this gives us a lot of speed and a whole lot of standards help viewer now supports HTML 401 that includes frame the tables and forms something you couldn't do and help you were before cascading style sheets levels one two and three such as it such as it is so far javascript one for dom level 0 1 and 2 including some microsoft dom extensions and support for netscape cookies netscape style plugins java applets more character sets than you can shake a stick at bi-directional text and contextual letter forms whatever those are seriously i probably don't even have the complete list what you should do since your help offers is go to the session noted there it's section 411 web standards it's ten-thirty tomorrow morning you'll hear from the Safari team from the people who implement WebKit and all the stuff they talk about works in help now and you can use it when you do that when you deploy Apple help and while you're there say thank you for me but there actually is more to help viewer we've done more than just implement WebKit we've made a number of changes that make so much faster and easier to use we've updated in standardized our download policy now help viewer uses the internet to retrieve remote content it wasn't very fast at that and in fact sometimes retrieve content women wasn't necessary what we do now is we use the cash more as you'd expect and we check the users network connection if the user has a network connection and has a good network connection meaning that the servers are responding quickly then we will ask the server if there is anything newer and if there is something newer we download it and put it into cash if there isn't something newer then we show what we have on the machine already that being either the cache copy or the local copy that you installed with your health system this is a good change that really speeds things up so you might say that we changed everything we certainly get made everything faster and we've adopted a lot of standards underneath the hood another thing that we've done is we've improved launch time by changing the way that index files are loaded now an apple help books are indexed for searching that's how we get to our searching capability and we're going to talk more about searching in a few minutes one change for Panther is that the health viewer expects to find the index for the book in the location where the indexing tool put it and it expects it to have the name that the indexing two will create it for it so please don't change the name of your index file and don't change the change its location now if you do help viewer will still find it it'll go traipsing through your book and find what it needs but as you man is you can imagine that slows it down so you can help all of us keep help you were faster by leaving your index file as it was created by the indexing tool now what I'd like to do is talk about how to deploy Apple help now the main point is that all of your existing content continues to work a book created for apple health and Mac OS aged five works today one thing you do want to do though is look at your content using the help you have on your pants or CD the renderer is different and every HTML renderer has slightly different ideas about font metrics and sizing and placement and that sort of thing so I'm very confident to what you have is going to look good but it might look a little different than it does under previous incarnations of the healthier so to be a good idea to look at it and see if you're happy with it and maybe make any HTML adjustments you feel or necessary you'll also want to look at your QuickTime movies if you have QuickTime movies in your help they're still going to work but previously help you or played QuickTime files natively now help you or use as a quicktime plugin this is a good thing because it gives you lots more parameters you can use with the embed command the quicktime plugin supports all sorts of interesting options you might want to take a look at those those are documented in QuickTime health and see if there are any you want to take advantage of now with panther if you don't change anything you can expect your QuickTime movies to behave as they did before so that covers the changes to Apple help for Panther let's spend the next few minutes talking about what Apple help is why you might want to use it and what you can do when you deploy your help look to take advantage of some of its unique features so what is Apple help well Apple help is the help system for Mac os10 it's built in and sort of the most visible component of that the thing that users interact with the thing the thing that we all see is the help viewer the help viewer is an optimized lightweight HTML browser and it's optimized for help delivery what we've done is we've built in a lot of features and a lot of careful attention to DUI to make sure that it is that it's good for delivering help and provide the consistent user experience if you went to John Glenn z's adopting aqua session yesterday you might remember that he talked about apple health is one of the key components of aqua and one of the checklist points for ensuring that you're providing a good aqua experience one of the reasons for that is that users turn to help when they're the most frustrated with their computer most users don't read the help just for fun they do it to find out an answer to a question they're trying to accomplish something they've reached an impasse we're trying to use you your UI or they have another question and they don't know how to proceed so at that point they come to the help by coming to the help viewer they have a consistent user interface one of they've seen before that behave the way they expect that provides lots of features one of which is full-text searching are searching is relevancy rank so when you type in your question you get a nice list of results back and the presentation of those results is similar to what users experience in other searching without throughout the system such as the finder and Sherlock and mail it's not a you it's not a part of the user interface that people have to figure out because it's difference in help than it is anywhere else now our search engine is really fast and it's really pretty good it supports natural language query so why you can type in burn CD or fire bad if you're the Hulk I guess it's better to type in something like how do I make a CD how do i record a CD to help you oral parse back correctly and give you the results in a nice relevancy ranks way another feature of health viewer is apple script based automation we have special helped colon URLs that can trigger an applescript so if your application is Apple scriptable you can provide links within your help that automate actions for users this is a great way to speed users back into using the interface and getting a problem solved you can automate things like changing preferences opening preference dialogues completing tasks for the user and so your instructions are shorter so they're less complicated and you just have a better experience with the help in your product it's another great reason to make your application Apple scriptable because you can take advantage of it yourself in your help system we've talked a little bit about the display of multimedia content help you or does that it now uses plug in QuickTime and / or built-in because they're distributed automatically with WebKit but as additional plugins are loaded into WebKit they become available for use and help you err this opens up a lot of interesting doors particularly if you're documenting a high end application and you need a specialized plug-in to display parts of your health content now you can do it healthier also supports remote and local content this is a somewhat hidden feature of the help but it's very powerful as a software developer this allows you to ship your applications help with your product and then continue to maintain that help on the internet as you discover what kinds of questions people are having as you discover mistakes in the documentation or other enhancements you can make you make these available to your customers simply by updating the copy of the help that's on your internet server help viewer retrieves it for you and displays it for the user when they have a good network connection we're going to talk a little bit later how to best take advantage of this feature of health and finally the last and perhaps most important advantage of using Apple help is that there are system wide api's for calling it certainly that's how the help menu works which we're going to talk about in a little bit but there are also other other ways to talk to help viewer that allow you to provide a good help experience for your users using things like help buttons and so on so maybe have soldiers you say wow Gordon that's great how do i how do I think how do i make my Apple help look how do I get started well it's really very easy and there are only four steps so let's go over them step one is dissolve up your help taunt head write your HTML now you can do this in whatever authoring tool you normally use bbedit Dreamweaver go live and now because we use WebKit and support web standards you can even use tools on other platforms that create help I know the lot of you use things like robohelp and so on you can get them to output in a format that supports web standards and will now work and help you err so the only thing special you have to do to your HTML over and above writing it like you normally would is to add one meta tag it's the apple title meta tag and the value of the tag is the name of your help book now this is a really important value you put this in the start page of your book your homepage whatever page it is that you want users to see when they open help viewer add this tag and it provides the name of your book to the system and as we talk about some of the other things that you need to do you'll see why this Apple title tag is so important the nice thing about this because meta is a standard HTML tag you can go ahead and add it to your content and even if you deploy that content elsewhere such as on your website it won't interfere with anything browsers all expected and just ignore it so after you've offered your HTML and added that meta tag step number two is to index your help for searching our search engine works because health content is pre be indexed to do this you use the Apple help indexing tool which you already have it's install them developer applications there are a few preferences you want to look at and decide to set one is to enter a remote root for URI for your content if you're going to put help on the internet and you want it updated and you enter an HTTP path in the indexing tool preferences you want to select the tokenizer for your language particularly if you're not using English which is the default and you want to turn on anchor indexing now anchor indexing is a very unique way for the help viewer to find content within your help book we're going to talk about it in a couple of minutes but basically it allows you to call an individual page and help without having to know what file it appears in so after you've set your preferences you take your folder full of your HTML content and you drop it on the indexing tool the indexing tool scans at all and come and writes out an index file that's used by the search engine now remember it puts that index file in the place where help viewers can expect to find it and it gives it a name the name is derived from the folder the name of the folders that you dropped on it help you is going to look for that file by that name when it loads so please just leave it as the index tool creates it and the performance will be better if you do change it it'll your help will still work it will just open a little bit slower than we'd like it to step number three that's a short one after you've added the Apple meta tag and you've index your content then you put your content inside your applications bundle that the local life resource you want to add it in the correct help Raj directory step number four this is hooking up your help menu now this is different between cocoa and carbon if you're a cocoa application you add two keys to your info.plist CF bundle help book folder which is the name of the help folder the name of the folders that you dropped on the indexing tool when you did the index and the other key is CF bundle help book name this matches the Apple title that you put in a start page of your help way back in step one this is how the help you er associates the name of your book with your application and the name that you use in the api's it's pretty simple just add those two tags next a cosmetic point but an important one an interface builder you want to change the item in the help menu to match your application instead of the generic name that interface builder gives you automatically now if you're a carbon app you do it slightly different you also add the two keys to your info.plist that we just discussed and then in your code after your initialize call h register help book and point to the bundle that contains your help this lets the help viewer and help system know about your book and associated with your application on carbon this call is taken for takes taken care of for care of automatically and Coco is taken care of automatically carbon you make this call and the details it's a sample code about how to do this are in the apple health tutorial rather than talk you through the code I want to refer you to their because it covers all of these steps and it gives you some additional information on the code and you already have that tutorial its installed the developer documentation on your systems so to summarize four steps create your content and add an apple help an apple title meta tag index your help so it can be searched install it in your applications bundle and then hook up your help menu and believe it or not you're done at that point you have a full working help system and you choose help from your applications help manual help you will open display your content and people will be able to search it can maybe even go home early that day but I hope you won't because there's a few things you can do to optimize your help and make it a little bit better so let's spend a little bit of time on that so one thing you can do to provide a really good help experience is to optimize your content for searching as Scott Forstall mentioned in his talk on Monday searching is really becoming a ubiquitous way of accessing information there's a lot of search language in the inner bass and a lot of consistent searching experiences that counts for help and when users are frustrated and they're coming to help find an answer to the question they know what it is they're looking for typing in a few words gets then to the answer in the most quickest way possible but that puts the requirement on you as the help offer to make sure that people can find your content by searching there are a few things you can think about doing one of which is to use the robots meta tag now robots is a standard meta tag is used by lots of search engines not just ours so you can go ahead and add it to your pages and it will work if you also put your health content on the internet for people to look at in their browser probably the most useful value for this is the no index robots tag no index tells the help search engine tells the search engine to not index any content in that page to make this page invisible for searching so why would you want to do that well a couple of key reasons one is you probably want to make your table of contents page not searchable it has a whole lot of words on it because it's your table of contents it covers your entire help book and if people search and find that it's not particularly helpful it just has a bunch more lengths and it might not be clear which one of those triggered the search result so make your table of contents no index another time you might want to do this is if you have a series of pages that you have people click through maybe you have four steps that each step is on a separate page when people are searching they might come into step 2 on page 2 or step 3 on page 3 coming in the middle of the procedure and be lost and not really kind of say well I don't understand what's going on here so in that case you might want to add the no index tag two pages two three and four making sure that when people search they only find page one and they get started on the right step now some other values that you can provide in robots and those are keywords and anchors so let's talk about those keywords are really important because when people come in and intercom enter search queries they're representing the task as they see it so you just think about how our users going to phrase questions how are they what types of words are they going to type in to look for this particular help content this is a way you can provide that on the page in an invisible way keywords don't appear to the user on the page they're not rendered by the HTML but they're picked up by the search engine and they're given the equal weight of the rest of the content so key words aren't weighted more heavily they're just treated as if they appear on the page normally but of course they don't appear on the page and one of the most common uses for this is misspelling or a synonym particularly a technology world as lots of technologies that real people regular people don't really know how to spell and even something like rendezvous can be challenging to spell for an English speaking of users so we try and keyword furthest spelling for that also think about things like discs and discs right hominem users might not be thinking of that one of what the correct form of the spelling is when they're looking for something relating to that think about the range of users you serve someone phrasing a question from an expert's point of view or from a very novice point of view you might want to include something like silver round thingy for cds which is what my father in law calls them for keywords are important things to add to your pages you just add them in there and do it once or twice they stay there for the entire life of your content and are picked up by the search engine automatically now earlier i mentioned an example of where you might have four pages and you know index pages two three and four so they don't show up and only page one shows up well that's a good strategy but you do have to think about what was on those three pages you just blocks from the search engine and are those words do those pages contain words that users are going to want to search for because they won't find them if you've no index them you want to take some of those key phrases and use them as keywords on that first page and that way people will find up page very easily another step you can do to make your help work really well in a search environment is to add page summaries now paid summaries are provided with the description meta tag and again it's a standard HTML thing lots of lots of search engines use description and so does help viewer and it helped viewers case the description shows up in the search results when the user clicks the result you see a little preview of what it is you might get when you click that page this helps users decide if they got in the right hit if that's the page that appears to answer their question if that's one they want to look at so these are easy to add they do become searchable content as well so they'll generate hits so again think about how users might be looking for your page and think about an appropriate summary that might give them the answer they need without having to actually visit the entire page itself and by kind of combining combining those two approaches you can make sure that search results work really well let's change gears a little bit and talk about how to further connect your application to the help system we talked about how to hook up your help menu and that's the minimum you should do that works really well you choose help from your applications menu and you have to help you or with your content but there are other things you can do to make sure that users get the type of content they're looking for depending upon the situation they're in now there are basically three ways you can call help you or directly from your app or from other places you can use a help colon URL you can do this in any HTML anywhere when the user clicks upheld viewer will launch and handle the URL that you asked for you can use an apple stripped tell help viewer to do something and of course there are see AP is the trigger things to happen in the help so what kind of things can you do when you call the health well you can perform a search give it a search string a phrase to look for and you can specify what book to look in whether it's your own book somebody else's if you think it will be installed such as Mac help or all of the books that to help viewer knows about you can also open a help book it's a very simple call and when you do that to help viewer opens to the page that has your apple title tag your start page and you can display a specific page and help so let's talk about that one this is typically what you would want to do for my help button as you see in the little illustration there a little button round button with a question mark you use this to provide contextual help this might appear on a dialogue or a preference pane and when the user clicks it they should see content that's specific to what it is they're looking at content that's targeted to the condition that they're in so you can do that by specifically calling a page the best way to do that and help viewer is to use an anchor now if your HTML author you're used to anchor as being a specific location on a specific page help you retreat them a little bit differently to help viewer an anchor is a thing that appears on a page in your health book you specify them using a standard anchor syntax like you see there when you index your content and turn on anchor indexing these are noted by the indexing tool and help you err resolve the locations at that time saying Ah anchor foo appears on page 1 2 3 HTML then when your application tells help viewer hey display the page with anchor foo it knows it's on 123 and displays the page for you you make this call using H look up anchor so one of the advantages of this is that you don't have to think about what page what physical page is in the file system that anchor appears on those people who are authoring the help can move the anchor from page to page even if that's you you can put on your other hats and move the anchors from page to page without ever ever having to go back and change the application to point to a different file another advantage this gives you is that help viewer resolve this anchor in the correct language so if you've localized your book the user is running in Spanish when you asked for this anchor to help viewer will display the Spanish page that has this anchor let's shift gears again and talk about remote and local content I've mentioned that we've optimized Panther a number of ways to make this work a lot better users no longer have to wait for content to be downloaded from the internet and that's a good thing we moved all the downloading off to the background but what does help you were do in this regards it's even more invisible now well there's basically two things that happen one is that if you have provided a remote root for your help look and again a remote group root is just that HTTP location somewhere on the internet if the user is connected to the internet and they have a good network connection that help viewers going to look at your remote group and see if there's a newer index file for your book if there is a newer index that it brings that index down and cashes it for the user what this allows you to do is continue to change and refine your health content over time you can remove pages and to do that you re and make sure if you remove the HTML file from your help book reindex the book and then put that new index file out on the internet when users pull it down because all searching is done through the index that page is now essentially invisible to your users more likely you can add pages if their pages you didn't have done or you didn't think of where you want to improve you can put those on the internet at your remote root re-index your health content put the new index on the internet help you'll help viewer will retrieve it automatically for users who can get to it and those new pages become available to the user they now show up in search results now those new pages are on the internet and they do have to be connected to view them but when they do view them they'll be cached and saved for the user for future reference so that's automatic index updating and how it works from the benefit it provides another level of internet support and help viewer is called internet primary this is different than index updating when you turn on the internet primary checkbox for your book and do this in the indexing tool or the preference for it this tells the help you er to prefer the content you have that you'll remote routes over the local content when the user requests a page when they click on a link help viewer will check to see if they have a good network connection and if they do it will check on the server to see if the pages are looking at is newer on the server and if it is then that page will be displayed if they're not connected or they don't have a good connection that it looks in the cash to see if it has a copy that it previously got or it defaults to the local content that is installed inside your applications bundle this is a really interesting feature of help viewer in it and it's one that is quite powerful though I found a talking to lots of developers over the last year since we've added this to help you or that it kind of requires a little shift in mindset in terms of thinking about having contents done and shipped with the product and then continue to maintain it over time but it's nice because it allows your help content to be as fresh and is up to date and is correct as people expect from the web but here there's actually experiencing it directly from your application instead of having to go off in a website and visit your support site to get the latest info now if you're going to do remote content with a couple things to keep in mind it's really good to think about organizing your contents with a single topic per page now this is really good for searching too because an remember in search results while user sees and the results list is the title of the page if you have several topics on that page puts a lot of burden on the title of the page to kind of convey to the user what all is included there if you break it up and it's easier to write a good title and so people understand what it is they're looking at and whether or not they want to view the page well short pages with a single topic are good for remote content too because they're shorter and they download faster another thing you can do is to set your cash periods now previously held viewer would delete items from the cache after three days unless they specified a cash retention period using the cash meta tag and the cash meta tag provides an expiration date it's kind of like the date on a carton of milk it tells help viewer when this page is bad and should be discarded now cashing looks a little bit differently since caching is handled through WebKit and other changes in the system cached pages stick around win their space and then and if space needs to be created then pages of specified expiration dates are removed first so if you want to page that you want to make sure sticks around and doesn't get deleted because space is needed you don't have to think in terms of three days anymore is have to think of I want to space to stick around so I'm going to give it an expiration date in the future it's okay to do that because in a internet primary situation will still do a compare of the page to the server and if there's a newer one will still get the newer page if it exists otherwise we'll use the one in the cache there's also some other cash directives and these are standard HTML things you can tell it to never cash a page which might be appropriate on a late-breaking news page or something that you want to get out to users temporarily but you think you're going to get rid of later you can also tell it to keep a page on nearly indefinitely by changing the cache expiration date to something very far in the future finally if you're going to use remote content think about the graphics through you're using you ship a large graphics that displays and help just fine with local content but in an Internet primary situation if you have modified that graphic on your web server helps we was going to see that it's newer and it's going to want to download it and of course if it's a big graphic then it will take longer to download there's something to keep in mind in regards to internet primary that eventually if you maintain it on the internet as you planned you will be triggering downloads for people and you might want to think about how big those are so in summary you've made a lot of changes to help viewer most of them are have been very long sought after and they're very exciting it's now much faster than it ever has been before it uses HTML standards which opens up a lot of new doors for content development makes it much easier to deploy your Apple help because you can use authoring tools that understand and create HTML that was invented after of 1996 and it's smarter about internet usage in addition if you've been thinking about using apple health and you weren't really sure what it was all about I hope you've seen that it provides a nice consistent user experience has a lot of interesting health features that are optimized for delivering content and it's very easy to author and implement essentially four steps to deployment now some of the details i glossed over a little bit but that's because you already have them available to you and they're very straightforward you have documentation is installed in your system under developer documentation you should also visit the apple health website which is an agc under user experience there's a lot of references there some additional documentation and some pointers and if you do have questions and comments here's how you can get a hold of the Apple help engineering team apple health comics group that apple com to group mailing address and so we all read it can't promise a reply but I do promise that we read them all and take them seriously and you can visit the apple authoring excuse me the help authoring mailing list this is a public list it's very low traffic go to list a plum and sign up for it there are a lot of Apple help authors on there who have tried various things and know lots of ways to deliver help post a question and you'll probably get an answer if you don't post anything you may think the list isn't isn't working because there's not a lot of traffic on it but generally people who will use it get what they need and several members of the engineering team monitor that list yeonggil NZ who is off busily preparing for the spectacular Apple Design Awards which take place this evening is our contact person information about your needs and apple health and future directions that you'd like to see should be emailed to him you