TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
My original query was about the tools used for writing Wizards, Tips,
Assistants, and online tutorials.
As usual, you all were very helpful. :-)
Here is a summary of the information you passed along.
*****************************************************************
GENERALLY BRILLIANT COMMENTS:
*****************************************************************
One big mistake I made the first time I got involved in this sort of effort
was to not realize that I'd need either my own part-time development
resource or some time and assistance from the development team. Integrating
tips, wizards, etc. with the application you're documenting is not trivial
if you want them to be contextual or to interact in a non-trivial way with
the app. I'd suggest you give the development folks a heads-up so they can
plan ahead and not be upset with you later when you need time and effort
from them that they didn't know to provide for.
--Brent L Jones, bjones -at- VersatileSoftware -dot- com
*****************************************************************
ASSISTANTS/CONTEXT EMBEDDED HELP:
*****************************************************************
I'm not sure what the official term for the MS Paperclip thing is. You'd
probably better make sure you know what they want before you start recruiting
for someone. And, once you know, keep doing what you're doing: find out what
it
takes to get it done. If they realize that it's going to take major programmer
time to implement something, chances are they'll drop the idea. Wizards
definitely are 90% developer time, 10% writer time.
--David Castro, thetechwriter -at- yahoo -dot- com
-----
I just attended an STC seminar where the speaker (Cheryl Zubak) touched on
the subject of Electronic Performance Support Systems. It wasn't the
subject of her talk, but she did provide a list of websites and books that
might help to get you started.
Websites:
www.workwrite.com (Cheryl's Site)
www.epssinfosite.com (Electronic Performance Support Info)
www.helpmatters.com (I think this is a site for information about online
help authoring)
www.keyworks.net (free downloadable HTML authoring tool)
www.research.microsoft.com (Microsoft's research site dealing with
electronic assistants and Bayesian reasoning)
Books:
Electronic Performance Support Systems, by Gloria Gery
Beyond the Nurnberg Funnel, by John Carrol
--James Pepper, James -dot- Pepper -at- smed -dot- com
-----
I don't think this is at all off topic. However, what you're describing
isn't a wizard (which is a series of dialogs that complete a task based on
user input and some default parameters). Cheri Lockett Zubak refers to it as
"context embedded help." Here's what else she says about it:
"Of course, these factors, and the relationships
among them, are things that have to be programmed
at some level. In addition, they involve very complex
and time-consuming thinking work. As a result,
context embedding tends to be much more
expensive and time consuming to create than other
types of embedded user assistance. "
Not that she's against--much the opposite. However, it requires much more
interaction with the application thahn a standard help system--and that
means a serious committment on the part of the application developers to
create hooks for that context sensitivity.
I'm not even scratching the surface of the technology involved for this. You
might try the WinHelp list (winhlp-l) to see if one of those developers can
give you more details.
--Bill Burns, BillDB -at- ILE -dot- com
*****************************************************************
ONLINE TUTORIALS:
*****************************************************************
I haven't had experience with either tips or Wizards (I doubt anyone here
will want those because we ALL eliminate the "annoying little paper clip" as
soon as possible!) but I have had experience with tutorials. Before going
any further with those, define EXACTLY what expectations are! If those
expectations involve multimedia, INSIST on several more members (and
experienced ones) on the staff. We had one person full-time and four others
part-time on a multimedia tutorial CD for a year and a half ... and the
results were not that impressive (we never DID get around to including
sound). Anything that involves complex images, animation, video clips, etc.
will be VERY time-and-talent intensive so just make sure you're properly
equipped and properly prepared!
--Gail Charette, gcharette -at- purelogicsoft -dot- com
-----
Winhelp has always had a feature called Training Card
help. I think it is highly underrated. It's most useful when you are
seeing a lot of screens and executing a lot of menu commands, because those
are the points where the context-id of the help plugs in to the application.
You need to work with the GUI programmer to get it finished. Meanwhile,
your job is to write a topic for every screen/menu command telling them
"what to do, and then...", so that when they finish entering data and then
execute the command, it pushes to the next 'training card'. If you want the
"wizard" face, either use animated gifs (you may have to get the company web
designer to sign on for that) or maybe design a wizard gui (get a GUI
programmer to sign on. This is NOT the job of a tech writer!).
--jane, judydh -at- total -dot- net
-----
A popular CBT tool is AuthorWare by MacroMedia. http://www.macromedia.com/software/authorware/
--Heather Beaudoin, heather -dot- beaudoin -at- eds -dot- com
*****************************************************************
WIZARDS:
*****************************************************************
Actually, that's not a wizard. A wizard is a dialog box with forward, back,
and
finish buttons on it. Each "screen" has some explanatory text, and you click
Next to move on to the next screen. Most setup programs these days are
wizard-based.
--David Castro, thetechwriter -at- yahoo -dot- com
-----
Hi Lisamarie, I came across this website from Microsoft for ya.... sorry
it's soooooo long, I don't know how to shorten it....but it'll do the
trick!!!! (NOTE: shortened version below...) http://www.microsoft.com/officedev/articles/wizard.htm
--Jackie Porter-Thomas, JackieP -at- sovereign -dot- co -dot- nz
-----
We're using InstallShield Wizards to install our Windows application
(pop the CD in, close the tray and PRESTO! Step by step installation).
Our fresh-from-college programmer who's "writing" the Wizard seems to
like the tool, at least there've been no profanity or chairs flying out
of his office....
Check 'em out, perhaps they have something you need. Here's their URL...
InstallShield(R) Software Corporation:
www.installshield.com <http://www.installshield.com>
--Tom Robinson, Trobinson -at- petrovend -dot- com
-----
Wizards are actually programs that guide a user through a process by asking
questions and displaying tasks based on how the user answers the questions.
The paper clip in Word is a natural language query, not a wizard. I don't
know much about wizards - too much coding for me! But WexTech has an
impressive natural language query tool that is easy to use and is quite
powerful for not only making a full text search more palatable to the user,
but it can also help you evaluate a Help system to see if it addresses the
issues that should be addressed. The tool is called AnswerWorks. You can
find out more about it at http://www.wextech.com/home.htm
--LuAnne Holder, LuAnne -dot- Holder -at- sota -dot- com
-----
wizards = programmers. it's that simple. for someone who has basic scripting
knowledge, say simple vbscript or javascript, you might take a look at a
product called Wanda the Wizard Wizard. it claimed to let neophytes make
wizards, but even if you can master this tool (even if it's still
available!<g>) you'll still need a programmer on the level of say, paul
o'rear. that is, someone who really understands how help works and how it
integrates with the interface. personally, i don't think it's something a
self-taught visual basic guy with a year of experience can do well. but
maybe your vb programmers are better than ours! <g>
warning: it takes more time than you might think.....<g>so please include
overage in your estimates, and also leave time/budget for extra testing!
--Fortune Elkins, Fortune -dot- Elkins -at- AIG -dot- com
-----
I've worked at one company where the product included Wizards.
The programmers handled all the technical aspects of making the
things work, which was just fine with me. Unfortunately, they
wrote 'em, too, which led to some pretty ugly and confusing
prose. I could notice and suggest edits, as I could with other
parts of the interface, but I wasn't given the task of actually
writing the things.
--Jan Stanley, janron -at- concentric -dot- net
-----
I don't know about help for the paper-clip type pop-ups, but I have done
help for Wizard programs (series of dialogs that lead the user through a
task). We added a Help button to each wizard screen; when you click this
button, the appropriate page in the .HLP file pops up. To do this, I have to
get the Map ID for that screen from the programmer. Then I plug this Map ID
into my RoboHelp project for the corresponding topic. Context sensitive help
requires you to work with a developer, and may be a bit tedious, but is not
really difficult.
--Ginger Moskowitz, ginger -at- aatech -dot- com
--
Lisamarie Babik
lmbabik -at- winspc -dot- com
Documentation Specialist
DataNet Quality Systems
24567 Northwestern Highway
Fourth Floor
Southfield, MI 48075
(248)357-2200
