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