Re: need advice - writing wiki Help for web app

Subject: Re: need advice - writing wiki Help for web app
From: Deborah Hemstreet <dvora -at- tech-challenged -dot- com>
To: techwr-l -at- lists -dot- techwr-l -dot- com
Date: Wed, 02 Feb 2011 15:53:11 -0700

I'm working on a Help project for a Mac. The SW is quite intuitive to USE - once you become familiar with it. But there are tons of wonderful features for the users that are simply not intuitive to FIND. Once found, they are easy. (I'd love to have more say with the programmers on that, but that is another issue.)

I've worked very hard to analyze the content and to be cautious about overuse of graphics. I place them where something may not be initially intuitive, and am using them as drop-down graphics, so that beginners can see the picture with the text, but experienced users can get to the meat of what they are looking for.

We are not using and videos, nor Flash, since the Help is targeted for Safari on a Mac, and apparently Flash and Mac are not the best of friends.

I'm in the final stages of preparing the Help and my client posted it on their secure site for their Beta testers. I'm quite excited because I made sure the testers were asked if they felt there were too many or too few pictures. All of them preferred the Webhelp to Apple Help, all said the graphics were appropriate and non-intrusive, and several said that they had already learned things they didn't know.

I share this, not to give myself a pat on the back, but to say that there is no easy answer for the use of screen shots or multi-media in your Help project. To make the right decisions you need to do the following:

1. Know who your end users are, and find a way to meet the needs of users at the lowest and highest levels without them feeling like you are talking down (or up) to them.
2. Have a client who WANTS to be involved in this process and is willing to provide as much information as possible. (I was fortunate to have that kind of client).
3. When a feature is simply poorly named, or implemented, be able to tactfully run it by your client and give them the pros and cons for change, AND suggest the change you are thinking of. My client was quite receptive and accepted, I guess 90% of my proposed changes.
4. In this case, I was also updating legacy documentation. Find out the rationale behind the legacy documentation, style, and use of graphics BEFORE making drastic changes. The information I gleaned from my client made it possible to delete half of the graphics used in the past, and necessitated updating most of the others.
5. Find out the anticipated way the Help will be used. And get as much information as you can. Nearly all the users for this Help will be Mac on Safari, but some will be using a MAC Emulator on PC (which has its own set of issues). Most of my clients users do not use IE.
6. Think about every graphic that is being placed in the Help. How does it contribute to the topic? Does the text repeat what the graphic says more clearly? Can you edit the graphic in order to call out the important information?

I know that everything I've shared here is really very basic, DUH information. But I've found that consciously thinking about these things as I write help tremendously in limiting the number of graphics, and making sure they are applicable to the topic when they are included.

I also have to admit that this was an unusually cooperative client who knew what she wanted from the outset. So I have a lot to be thankful for.

I hope these thoughts are helpful.


Create and publish documentation through multiple channels with Doc-To-Help.
Choose your authoring formats and get any output you may need. Try
Doc-To-Help, now with MS SharePoint integration, free for 30-days.

You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-

To unsubscribe send a blank email to
techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit

To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com

Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit for more resources and info.

Please move off-topic discussions to the Chat list, at:

Re: need advice - writing wiki Help for web app: From: kafkascampi

Previous by Author: Re: creating a portfolio -- writing samples
Next by Author: Re: Special characters, such as TM, in web page titles
Previous by Thread: Re: need advice - writing wiki Help for web app
Next by Thread: Re: need advice - writing wiki Help for web app

What this post helpful? Share it with friends and colleagues:

Sponsored Ads