WWDC2001 Session 125

Transcript

Kind: captions Language: en welcome to session 125 about Apple health 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 a 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 is sort of being the last thing they do for their application and really it's one of the basic building blocks for your Mac os10 products 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 helping 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 10 product all right fantastic so that's really great so what we want to do in this session is we're gonna you know I mean we're gonna do a formal session we just want to have a laid-back 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 API is and all that sort of stuff and then we've also got some really cool announcements so I'd like to welcome Gordon Mayer on stage from our instructional products group at Apple and he'll walk you through some of the basics here [Applause] hi everyone thanks for coming it's good to see you all I've been looking forward to the session all week so let's get right to it this is our agenda for today we're gonna 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 gonna 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 a Apple help book you'll see that you can take a 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 to 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 API is how to handle your help menu how to put help buttons and dialogues and so on and you'll be pleased that they're to 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 applications shipping on ten 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 the 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 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 readme your website all of those things contribute to user experience into the user education but so does the UI of the application help tags error messages dialogs 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 onscreen help system you know that your user is 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 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'd burned some of my favorite songs on a CD and I wanted to make a CD label so I watched illustrator and I drew a couple of circles figured out how to meet how big they needed to be typed my song titles in and so on and I wanted on the label I wanted a title for this CD but I wanted the title to kind of curve around and you know 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 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 right I looked around me and one of my colleagues and so kind of 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 right and decide well who cares if the text is curved or I could turn to the documentation turn to the how and try and find my answer which is what I did and I got in there and I family 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 the minimalism is this entire school of thoughts 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've 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 right people come to the help with the 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 a documentation they've 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 to 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 looking 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 turning pears is probably an advanced user they had they bring a lot to the table about font technology acknowledge that as you provide instructions you know we've all had the experience attorneys to a help system and finding the information they're either too basic or you know not quite complete it wasn't speaking to us at that point as a user and the thing about help systems is is once the user comes to it and looks at it if they don't get help they're unlikely to ever come back and check it again because it wasn't successful but if they turn to the help and have a good experience and get the answer they're looking for they'll come back and even be more forgiving because that initial good experience sticks with them another high-level principle you can use is to exploit the environment right the on-screen help system is on screen and on the computer it's not a printed book you can do things that 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 on ebooks 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 the 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 right 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 out of computer the user has probably come with a problem and it's following your instructions along if the UI speaks to the user and enforces conditions such as clicking okay 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 on spring help as it is in a book so yeah I know what some of you were 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 os10 and you want and to do that you just need to provide a consistent help experience an 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 like oh well gee what what are these well a similar situation happens with the help if you roll your own help solution and then don't use the help viewer when your customer comes and looks up the help they're 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 tried to optimize it for the on screen environment let's take a look at it in action this is Jess Jessica's the tech lead for Apple help and she's gonna 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 you er it's kind of the core of Apple help it's an HTML display application you see it here on screen has a little opening animation we've included in Mac help to welcome that 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 in a status area across the top we have a very simple interface for searching we have a large text field and a nice nice pulsing ask button because we want to encourage people to search so if we've typed in a search string while we go ahead and click ask and see what we get so that fast to help you were searched through all of the content and Mac helps some 300 pages or so and it presented it a relevancy ranked list of results those are topics that are most relevant to what just 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 but 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 we've 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 that 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 so 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 implemented help and of course as a Mac os10 ad program the help viewer is completely international can display whatever you need 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 you wear 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 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 see a little status message in a progress bar up here 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 a good content also here is a another another the link at the bottom this one does 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 see on 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 relative 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 Jess so we've talked about how help can be a benefit to users in providing a good consistent user instruction experience on Mac os10 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 offer a Polly I am L authoring tool you choose anything from a go live or a Dream Weaver to BB at it to stick ease 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 os10 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 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 clicktime can play it and you can use it in your help system and again by saying we would play QuickTime natively I mean we do not use the QuickTime plug-in we use the Sherlock engine for searching that's how we get our fast searching and our relevancy ranking you can launch Apple script 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 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 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 we 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 you or prefers local content it always looks locally first and buy 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 that every user has a help cache and the help cache contains files that were recently downloaded if it doesn't find them in the users 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 its 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 this 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'll 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 local graphics with no 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 it's like a hunting dog and it will sniff it out and find it in any of these locations you don't need to make sure that all of your H refs 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 3.2 you take your start page the main page for your help book it 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 a type Apple title and the name of your help book in this example my app dot help add that to your one page this is a standard element so other systems are gonna ignore it you can continue to deploy this information on other 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 the 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 sites 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 os10 help resides inside your applications bundle all the localized help can live there just like all the other localized resources with Mac OS 10 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 add a help menu we recommend a single item in there in this case it's male help in this slide should be obviously be your applications name help with a command question mark is the keyboard shortcut so why do we recommend one item well you know in user test is interesting we've sat through 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 and 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 are kind of is 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 excuse me one of which is Apple script you saw in the demo you're able to launch Apple scripts and automate things anything you can do with an Apple script you can do from Apple help you have the user click a link and it will execute this is a great reason to make your application scriptable automating tasks for users is a great thing they like it you know when we first came up with with doing this in Mac help and we interview when we started doing a lot of this we were concerned that when a user uses an automation they might not be learning anything they might become reliant on that observation on that automation so we set up some user studies and what we did is we tested earlier early in this study we had somebody do a task and they had to come to the help for information on it and we provided an automation that would we do that task forum and 95% maybe 99% I'm here 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 enabled to successfully complete that task they had to undo what this automation had done for them earlier we wanted to see if people were gonna 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 to not impede their ability to learn how to work 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 onscreen help system one of the best ways to find things is by searching come to help with a representation of your tasks 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 gonna 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 quick time you can also use the robots meta tag this is a standard tag if you run a website 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 and 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 just kind of being at ease so you use robots to omit that page from searching and that when people search they hit the pages with the real content on them Apple abstract is another one is another metatag 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 gonna learn if they click on that it makes it make 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 I make a more educated choice when they go to download that page anchor look up 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 0 0 1 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 to 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 you ER show me the page with printing zero zero one 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 the content up to date as I've said if you're going to implement it here's a couple things to keep in mind we 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 we'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 jpg average if it doesn't have to be an animation but a reference movie is very small just a couple of K the help you er 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 gonna 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 I'm excuse me you can implement I'm not gonna 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 I start I'll start with help colon which is a special handle or 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 could switch to another book for example if you want to take somebody to Mack help you can include include a link in your content that says open Mack help for me when they click that help brew or go find Mack 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 a search term and of course you can run an Apple script here's the syntax for that it's a help colon 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 generalise 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 you get to start how to how to create a help system very quickly and get it into Mac OS 10 how to take an existing HTML book and convert it to Mac OS 10 but what if you're not starting with HTML and although many of you are coming from wind help or quick help have existing help systems you want to get into the system well if you're coming from Apple guide there is a utility from our friends at guide works 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 we run it through this utility and it will give to 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 win help or quick help well we have some really good news for you that's with EA and the announcement we alluded to earlier and to talk about that I'm gonna ask John to come back up on stage and thank you for your attention [Applause] so I interview 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 in 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 on in 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 they're unique to Macintosh that aren't available and say on another platform or don't exist on another platform and one of those barriers are currently was a lot of people are coming from Windows to Mac OS 10 and they have content on Windows and well didn't win help format and they needed to get out that over to Apple help and so I want to introduce somebody that we've began to work with the Jack Minsky from software Mac you've and to talk about a tool that they've come up with working with us at developer relations so my name is Jack Minsky I'm the president of software Makia we are the world's largest conversion house moving stuff from Windows to Mac some of the titles you may have heard of it we moved the world book multimedia encyclopedia we did for world book I VM Mavis Beacon teaches typing we did SimCity 3000 kid picks deluxe SPSS ten and a couple of hundred others more recently we've been moving things to Mac OS 10 and we've also done some web objects projects basically any Apple technologies need to be implemented as you were moving projects to Mac OS 10 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 used extensively called quick help 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 macintosh very nicely the problem with quick help is it doesn't have a Mac OS 10 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 bass for Apple help I'm finding that took us 2 to 3 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 and we've made it into our first product that we've 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 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 it takes a couple of minutes to run but then you still need to do some converting by hand if you're starting from Wynn help or robohelp you'd need to change all of the right mouse clicks to control clicks and those kind of things still uh stood on my hand of course you'd have to replace screenshots but the basics of getting it from RTF help dividing it into those small chunks for HTML help is all done automatically so what it does it takes RTF help was it HTML help and again win help and quick help files and like to show it to you so we start by launching quick help quicker help sorry I like to see the bouncing shoe go so I always want to put the doc out okay 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 a course because this is Mac we can use drag-and-drop and I've identified here my what's called an HP J file those who made quick help before no this is the the basic index file for the product and so now that's set and selected one of the things that we need to do is to check footnotes if you're interested in doing that this takes about 25 seconds here I'm wild do not explain why I'm a quest and of course we can have footnote names as long as you want up to the maximum that Mac os10 will hold but if you're making carbon product you'd need to limit yourself to 27 characters and so you want to check that the footnotes actually are within those parameters and this will identify then all of the footnotes that are longer than 27 if you don't go through this process will truncate at 27 characters but you might not want to do that you won't want to name them to something that's more interesting or more memorable for you so you can see here we've got an edit file and it allows us to change each one we could go through manually in this particular file there were about 20 out of 500 footnotes that needed to be trimmed up and you can go ahead and change that we are going to check those we're allowed to automatically truncate the other preferences that we can set in getting over we can map fonts so we have here a couple preset in the default but you can fill this up with as many as you want and you can also map sizes from different point sizes most people have their RTF help in 12 point which would convert over to an HTML 3 but you can go ahead and add any combination you want or change the ones that are already in here additionally we can change the title so we can go ahead and select the the title size you can either select the RTF settings where we can set it based on HTML tags release here or you can set it manually to anything that you like one more thing we put in a lot of people like to add something before or after each body of text and help maybe it's a small graphic or a line rule or something else whatever your taste is so we've allowed fields before and after each body of text to be able to add something on and then finally something that is nice in the graphics rich environment at Apple help is to be able to create a frame set for that opening page to make that look nice and we're going ahead and do that now we're gonna do is select something for the left frame and we'll go to the desktop here and we have a couple of pictures we'll select that for the left hand side select the main one on this side and one of the other things that we've we've done here because certainly for ourselves where we're making lots of different help files for different projects but you may have two or three different products and not want to go through and set these each time we've allowed you to save the set so we'll call this one Jax help set 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 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 okay and we've saved our our preferences and that's it and then we're ready to convert you know let's give it a spin I'm going to choose a place for the destination folder I'm gonna put on the desktop so we can see it and create a new folder and I'm gonna call that one Jack's help and create that on the desktop and it starts converting this process are gonna take about another minute and a half so he gave me a chance to tell you about a few of the other features we did show this at the expo those 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 into preferences as well that's helpful if you're doing your own editing or you want to give it to your QA group to try and check through the help 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 will be given a choice to with two options we can open up the folder that contains this helps that you're going in and take a look at it maybe start to do some editing right away or we can open up the the final result just take a look at it an Apple help I'm not gonna open up the destination folder we all will open Apple help and there it goes that 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 see for those of you remember what quick help looks like well this is the opening quick help page this is the opening Apple help page you having 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 the same content problem so these are exactly the same or at least the same content there you go and that's what it does simple as that [Applause] 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 595 for the SDK the same price for those of you have used alter quick call 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 jack atma kiev comm write that down or wwm achieve comm 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 happy to answer whatever we can thank you [Applause] so that's just an example of some of the tools that we're hoping to bring to to the platform to help you move your help content across and even other stuff in other domains and other technologies on Mac os10 if you have some specific tools that you're using that you think would you know we would you'd love to have Apple produce or work with you know third-party developers to Bruce the conversion process or whatever please contact me at the end of the session my contact name full 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 Khan on stage from the she's the tech lead for Apple help at Apple and as she's gonna walk you through some of the api's 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 health viewer does to display it to the user and how to create a health book what I'm gonna talk to you about is the help menu on Mac os10 listing your book in the Help Center which is that main table of contents in the health viewer and accessing help from your application using menus buttons or contextual menus and then we'll bring up Jack John I'm sorry for Q&A so Gordon mentioned before that the basic health menu on Mac os10 is what we recommend that you use and it's a single item your applications name followed by the word help with the question mark e is the keyboard shortcut how do you get the basic app Minh help menu on Mac os10 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 do 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 the bundle identifier in the bundle name I'll go into a little more detail about our special keys now so that's CF bundle health 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 wasn't on my computer anyway that's the help folder down in your app package and this graphic displays your app once once it's been built that's where if you had a global help book folder it would be and the CF bundle 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 key with key that you might define in your in your strings file rather than your main info.plist okay 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 CF bundle help book folder as you can see is a string value my app help folder the CF bundle help book name folder is help with 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 calm your company name dot your app name and your CF bundle 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 P list and you put your help folder down in your app bundle and you'll launch your app you're going to 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 going to want to have multiple help menu items doing different things so an example of a custom help menu is BB edits help and guess what you can do it using Apple help too 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 api's 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 ApS 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 P list is just that you set an array value for CF bundle health book folder and you can put your single string inside that array or if you want to shoot multiple help books we allow that too and so you would create an array and list your multiple help books 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 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 at each time your app launches because if the registration is already current it's basically a no op you're not going to 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 helpless keys that we discussed for your info.plist 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 plist keys to have a basic help menu just work the caveat 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 gonna 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 help to appear in the Help Center list and at first that 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 for your 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 this stuff and launch project builder and how about hide the dock whoops where's PD okay so first I'm going to 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 going to 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 gonna 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 so now a 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 gonna 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 let's 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 health 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 a 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 health book as a single resource a single entity that gets copied around so there it is now inside there I've got you know one HTML file that's wow that's a big fun 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 going to be one of my plist key values the other one is the actual folder itself that I've added to my app bundle oops so let's go set those keyless keys rather be with 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 comm dot a palang demo it 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 gonna add a new sort of top-level key here and call it CF bundle help look folder because we want the basic help menu for free we're gonna leave that as a string value whoops and then it's gonna move it for us so that it's hard to click in and we're gonna 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 carbon demo help past that we want to add one more sibling and that's the CF bundle 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 ok 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 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 and 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 initialized with the snippet that also contains that initialized call okay so let's expand this that you guys can see that it's not that big a deal to register your book okay 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 CF Bumble calls using that you can get the FS ref and then you pass the FS ref to the H 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 twelve lines of code or so it's not that bad alright I think if the demo gods are with me we're ready to build and run okay now let's make sure that help you er 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 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 health system and Apple help on Mac os10 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 just finished creating that alright so similarly we're just gonna open up this resources section and add our hub 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 only surprises me okay so see if bundle Help book folder with KOCO 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 just to be really a little bit anal about this let's make sure that our help menu is gonna look right so this is the nuance for Coco 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 up and run our app here we go we've got the help menu cocoa demo help and without adding any code you're gonna see that help viewer is going to launch and display your help so it's as simple as that glad that 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 10 now I'll briefly just cover the Apple help api's 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 capi they're usable by cocoa apps as well they're available in carbon Live 1.1 and later for carbon live applications there are five of them we already talked about the first one two more go into a category of opening health 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 age go to main TOC to open the health 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 10 the third is using H go to page 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 health viewer and go to the main page of your apps health 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 health book you can also do lookups and searches I'll briefly cover actually the last two on these slides age search is used it's the programmatic way of doing a help colon search URL and it basically it causes help you were to open and perform a search if you're familiar with the Apple guide api's that's similar to the AG open with Search API the top one is the one that I really want to stress that's a hlookup anchor 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 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 gonna work finally for more information you can see these URLs I believe that you guys are going to get a main URL at the end of this that is going to contain all these so don't worry about writing in the bone 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 carbon Lib SDK the latest version that contains the help viewer for carbon Lib which you'll need if you're a carbon web app and you want to use our API and also the newest help indexing tool which is what contains the anchor indexing who to contact you can use these email address and these lists to get insider information about Apple health if you've 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 jungle NZ 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 form for aqua curd carbonyls to all those occurred but you can watch them on DVD when that set comes out 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 you