It’s been a few weeks and I am starting to feel like writing about some polish. In our last installment of Mac Polish we discussed what constitutes a good toolbar for a Mac application.
In summary:
- Hire a professional icon designer
- Use illustrative imagery
- Imitation is the sincerest form of flattery
Today I want to cover what your users do when they are in need of help. I was inspired to write this because I got some feedback about saying that a Mac application must use the Apple Help Viewer.
Help Viewer is the primary system for Mac applications to deliver assistance to users. Apple help files are built off of static HTML pages that are searchable, updatable (the data can be stored online) and able to support a wide range of digital media.
When I suggested that all Mac developers should have their help system interface with the Apple solution, Neil Lee gave me some grief about it. He says:
Even in Mac OS X 10.4 the Help Viewer applications is atrocious. The search barely works, you can’t print the entire documentation out (creating double the work for a developer that wants to provide printable docs), it’s not bookmark-enabled, and much, much more. I personally find it very awkward to use.
He says that search barely works in Help Viewer. That’s untrue. When you index your help files using the Apple Help Indexing Tool, the full text of your documentation is indexed as well as meta keywords, abstracts you embed in your files, anchors and the segments included.
One of the keys to making search suck less is to use a good set of keywords for each topic in your help documents. When I write documentation, I try to include every possible keyword I can think of that describes what the page I am writing is about. The more relevant keywords you have, the more likely your topic is going to pop up.
Obviously, there isn’t much a user can do about developer’s writing poor documentation besides complain. This is why I believe developers should outsource their documentation if at all possible (hey, hire me). Just like I said developers shouldn’t be designers as well, they shouldn’t be writers either. Outsourcing the documentation of your application has several advantages.
- A fresh set of eyes: When you have someone new write the help for your application, you are letting a new user become adapted to your application, learn it’s workflow, and write according to it. Since you have seen it from it’s infancy to release, you may not be able to see the application from the eyes of a new user.
- Professionalism: Hiring someone who has experience writing is a win-win situation for you and your users. You don’t have to worry about the wording and grammar of your help, and your users are getting an in-depth, understandable first line of support. If you have exhaustive, professional help files, it can help keep your support costs down in the long run.
- Understandability: This may not apply in all cases, but I know that many developers are better at writing code rather than writing understandable help files. I am sure you have had the conversation where you try to explain a topic to a novice, and they don’t understand you: too much jargon is a common reason. Letting someone write from a user’s perspective rather than a programmer’s is advantageous.
Later on Neil says:
In 10.4 now that PDFs are so well supported (searchable, bookmarkable, etc.) I think all applications should switch over to PDF-based documentation. The two downsides to this that I can see is the lack of ability to include embedded content (like QT movies) and probably some increased file size. But besides that, it’s a superior option.
Wrong. Having every application use a PDF document means that there is little to no consistency in the design of the documentation. When you open the Help file for most applications that take advantage of Help Viewer they tend to have a uniform theme: a logo on the left side and main content sections in large letters on the right. From there, you can jump to specific sections of the documentation.
The biggest problem I have with using Preview and PDFs for documentation is search. When you search in Help Viewer, you are given a title and a relevancy score. With Preview, you are given a short snippet of text and a bold text of the words included in your search string. That is not useful at all in most instances. For example, in the PDF copy of my Oracle reference, when I want to find information about the DECODE() function, I get an output like this:
Now, compare that to putting in a keyword in Help Viewer, and the search results are far superior.
If Apple wanted to improve the search results in Preview to be more “Help Viewer”-ish I would be more open to the transition of PDF based documentation. Until then, developers need to embrace the standard help system Apple has put forth for their users.
