What Programmers Really Want:
Results of a Needs Assessment
for SDK Documentation
Janet Nykaza
Rhonda Messinger
Fran Boehme
Instructional Designer
Learning Solutions Group, Inc.
PO Box 1165
Portage, MI 49024, USA
+1 269 324 6067
Instructional Designer
Learning Solutions Group, Inc.
PO Box 1165
Portage, MI 49024, USA
+1 269 324 6067
Senior Manager, Net Solutions
and Employee Training
Rockwell FirstPoint Contact
300 Bauman Court,
Wood Dale IL 60191, USA
+1 630 227 8917
jnykaza@
learningsolutionsgroup.com
rcmess@
learningsolutionsgroup.com
fran.boehme@
rockwellfirstpoint.com
Cherie L. Norman
Matthew Mace
Manuel Gordon
(formerly with
Rockwell FirstPoint Contact)
AVP—Instructional
Design/Communication Manager
Financial Systems Training & Web
Bank One Corporation
Bank One Plaza - IL1-0780 /1ND-6
Chicago, IL 60670-0780, USA
+1 312 407 1219
President
Granite Solutions, Inc.
550 West Centre Ave
Portage, MI 49024, USA
+1 269 324 8231
Partner
Gordon & Gordon
139 Abbott Avenue
Westmount, QC H3Z 2K1, Canada
+1 514 934-3274
[email protected]
manuel@
gordonandgordon.com
Cherie_Norman@
BankOne.com
ABSTRACT
Categories and Subject Descriptors
This paper steps the reader through a needs assessment of
programmers that was conducted by instructional designers. The
assessment’s purpose was to identify what learning support
programmers need and want to successfully use a new software
development kit (SDK). The paper includes the challenges the
researchers encountered, the questions asked and the responses,
the types of individuals interviewed, and the conclusions reached
from the research. Recommendations also are presented. Those
responsible with developing documentation, training, and other
learning support systems for programmers may find this
assessment helpful. Marketing, product development and
customer support people may also find value in learning more
about the needs of this unique audience.
D.2.7 [Software Engineering]: Distribution, Maintenance, and
Enhancement---Documentation; H.1.2 [User/Machine Systems]:
User/Machine Systems---Human factors.
General Terms
Documentation, Human Factors.
Keywords
SDK documentation, API documentation, programmer
documentation, developer documentation, needs analysis, needs
assessment.
1. INTRODUCTION
This paper presents the results of needs assessment field research
about application developers working with a new software
development kit (SDK) designed by Rockwell FirstPoint Contact.
Instructional designers from Learning Solutions Group, Inc.
performed a needs assessment for Rockwell FirstPoint Contact
based on interviews, focus groups and site visits with 50 people.
Targeted individuals were programmers (customers, potential
customers, Rockwell FirstPoint Contact staff, and systems
integrators) who had used the SDK or who were potential users of
the SDK.
Permission to make digital or hard copies of all or part of this work for
personal or classroom use is granted without fee provided that copies are
not made or distributed for profit or commercial advantage and that
copies bear this notice and the full citation on the first page. To copy
otherwise, or republish, to post on servers or to redistribute to lists,
requires prior specific permission and/or a fee.
SIGDOC’02, October 20-23, 2002, Toronto, Ontario, Canada.
Copyright 2002 ACM 1-58113-543-2/02/0010…$5.00.
This paper was first published in slightly different form by ACM.
–1–
This version provided by Gordon & Gordon: http://www.gordonandgordon.com
The ultimate purpose of the needs assessment was to determine
how best to enhance the current training and learning support
provided for customers of the SDK. At that time the SDK was a
new, limited released product.
An on-site, one-day instructor-led training with an accompanying
PowerPoint presentation. The instructor was an application
developer who worked for a different department. The
PowerPoint presentation, with no instructor, was available
for self-training.
The needs assessment (also known as a needs analysis) focused
on:
Sample applications written in Visual Basic (installation CD).
The desired and required content of SDK documentation.
A CD-ROM course that introduced basic call center concepts. It
was developed for a wide call center audience, not for
programmers in particular, so 3CS SDK was not included.
The audience for SDK documentation (programmers): skill,
knowledge, aptitude, experience.
The most cost-effective way of supporting the programmers as
learners.
As well, programmers had access to the GUI-based application
designed by Rockwell FirstPoint Contact for use by call center
supervisors and administrators. This Administrator’s GUI gave
programmers a high-level, practical view of 3CS data entities and
what could be done with them.
The SDK was the first software development kit developed by
Rockwell FirstPoint Contact that interfaced with an openarchitecture environment. Learning Solutions Group had no
previous experience with SDK documentation and training. The
instructional designers, therefore, had no preconceptions about
what programmers wanted or needed nor did they know what a
company planning to sell an SDK should include in SDK
documentation and training. Instead, they worked with their
client, the Knowledge Center department of Rockwell FirstPoint
Contact, to find out first hand.
Rockwell FirstPoint Contact wanted to increase customer
satisfaction with 3CS SDK by facilitating its installation and use.
It was selling the first version of 3CS SDK to its customers and to
third-party systems integrators who wanted to develop their own
custom client applications on top of Rockwell FirstPoint
Contact’s 3CS product. The Knowledge Center had already made
the decision to enhance the learning support provided to
programmers using the SDK. They were considering access to
future support materials via the World Wide Web, but wanted the
needs assessment results, if appropriate, to drive this initiative.
As a result, the report was quite complete and remarkably fresh
and vigorous in its insights. This paper is an adaptation of that
report for a wider audience.
The department contracted with Granite Solutions, the first
systems integration customer for the SDK, to participate in the
needs assessment. To ensure impartial results and a more open
discussion environment for the assessment interviews, Learning
Solutions Group was contracted to perform the needs assessment
to determine what learning support materials were needed based
on the results.
How documentation and training is used by programmers.
The best delivery methods for various learning support tools.
The needs assessment was done for one particular SDK, so the
results cannot simply be applied to all SDKs and all companies.
Nonetheless, the authors believe the conclusions may be useful to
people responsible for developing, marketing, and supporting
SDKs, particularly the people responsible for documentation and
training. In addition, the research results demonstrate how much
useful information about an audience can be obtained by spending
time and money on empirical research. Finally, this paper can help
people who want to perform a needs assessment for their own
organization.
3. HOW THE RESEARCH WAS
CONDUCTED
Telephone and in-person interviews, focus groups and site visits
were used to find common trends and facts about the intended
audience of the SDK and how the SDK would be used. A total of
57 people were interviewed. They included:
2. BACKGROUND INFORMATION
Programmers working for customers.
Rockwell FirstPoint Contact develops solutions (products that
include hardware, software and services) for companies operating
call centers (also known as contact centers). A solution consists of
specialized telecommunications hardware, commonly called an
Automatic Call Distributor (ACD) or switch, and related software
and services.
Systems integrators with programming staff, or who also did
programming.
Rockwell FirstPoint Contact technical and management staff.
Additional information was gathered regarding what would hold
true for all SDKs and what was unique to the 3CS SDK.
One piece of software that interfaced with the ACD was called
3CS. This server product was an open-architecture environment
that interfaced with the ACD. Simply put, the 3CS was a real-time
database. The company developed a software developers kit,
called the 3CS SDK, to provide programmers with the ability to
write custom client applications that interacted with and used the
real-time data stored in 3CS.
The CAUSE© analysis method was used to analyze the content,
audience, use, structure and evaluation of the SDK.
3.1 CAUSE© Analysis
In conjunction with Granite Solutions and Rockwell FirstPoint
Contact, Learning Solutions Group researched how to best
enhance the SDK learning support system using the CAUSE©
method for analysis. This method examines the Content,
Audience, Use, Structure and Evaluation necessary to guide
learning and motivate users to apply what was learned.
Before the Knowledge Center became involved, other parts of
Rockwell FirstPoint Contact had developed the following support
materials that were included with the just-released, first version of
the 3CS SDK:
The original needs assessment goals were translated into the
CAUSE method as follows:
A 154-page Programmer’s Reference Guide (paper document).
This paper was first published in slightly different form by ACM.
–2–
This version provided by Gordon & Gordon: http://www.gordonandgordon.com
Audience
Identify the typical users (that is,
programmers).
Audience
Identify prerequisites for programmers who
are developing applications using 3CS SDK.
Audience/Use
Content/
Structure
Content
Content/
Structure
What is your knowledge and experience with programming with
ActiveX? (The 3CS SDK was developed using Microsoft’s
ActiveX technology.)
What is the formal and informal education of the actual users (that
is, programmers) of the product?
Determine the typical user’s learning style
and preferred learning methods and supports.
How many users are there?
Evaluate what support currently exists for the
3CS SDK (current product Information,
internal web systems), how it works and how
it could be integrated into a total support
system.
Will all users be trained at once?
Identify the learning that will support the
company’s business goal of enhancing the
marketing and customer support services for
the 3CS SDK.
Is call center experience necessary?
What additional barriers do we face in addressing this audience?
How do you like to learn new software?
How do you like to have software supported?
Is experience with other Rockwell FirstPoint Contact’s products
necessary?
Is Visual Basic or C++ experience necessary?
Determine what should be developed and/or
improved to complement the current support
offerings.
Structure
Identify the best delivery methods for various
support tools. The learning support may be a
combination of delivery methods: CD-ROM,
printed reference and/or self-study tutorial
material, web-based, video.
Structure/
Evaluation
Determine the most cost-effective way to
support learners (programmers).
Evaluation
Determine how best to measure the learning
solution’s success.
3.2.3 Use
Learning support needs to fit with how the learner will use the
information. Do they need a laminated page that they can carry
with them? Do they need to have total recall of the information or
can they look it up? To determine this, the researchers asked
learners (programmers), system integrators and management the
following questions:
How will the information be used?
What are learners expected to do with the information?
What barriers stand in the way of learners using the information?
How frequently will the information be used?
3.2 Questions Asked of Interviewees
3.2.4 Structure
The questions asked of the interviewees are listed below, grouped
by CAUSE© analysis categories.
Determining the appropriate structure for learning and support
requires input from management, customers, integrators and
programmers. Adult learning theories can also be applied to the
mix. Ultimately, however, the format must work for the
programmers’ preferred learning style and time constraints. The
following questions were asked:
3.2.1 Content
Subject matter experts, product management representatives and
users of the SDK were asked the following questions to help
identify what information should be included in the 3CS SDK:
How long of a learning experience would you like?
Who are your 3CS SDK experts within Rockwell FirstPoint
Contact?
In what format do you prefer to learn? (Computer-based, self
study, presentation, workshop, or other.)
What content will improve the use of the SDK?
Why do you feel you would be most successful using this
method?
What new skills need to be learned to use the SDK?
What related knowledge needs to be learned?
Do learners need to memorize or know this information or should
they just be able to find the information in resources?
What information do you want to share about the SDK?
What specific points would you like to make about this
information?
3.2.5 Evaluation
A learning support system for a new product must be judged on
how quickly and easily the learners are able to find and use
information to make the product function the way they want. The
objective of the learning support must be articulated so that the
company can evaluate the success of the system. All interviewees
were asked:
Is there any specific terminology that the learners must know?
3.2.2 Audience
The audience is the computer programmer who will develop
custom applications using the SDK. (The audience may vary for
different SDKs.) To assess the audience, the following types of
questions were asked of management, systems integrators and/or
actual programmers:
How will you know if this learning support program is successful?
What changes will you see?
What form of evaluation will you do on the learning support
program?
Who in your organization will learn and use the information?
What is your knowledge and experience with call centers?
This paper was first published in slightly different form by ACM.
–3–
This version provided by Gordon & Gordon: http://www.gordonandgordon.com
3.3 Interview Subjects
4. RESEARCH RESULTS
This table groups by job categories the fifty people who
participated in focus groups, interviews, and site visits. The
“Research Focus” column describes the type of information the
researchers gathered from those in the respective groups.
This section contains selected research results that the authors
believe may be useful to people responsible for developing,
marketing, and supporting SDKs—particularly those responsible
for documentation and training.
Interview Subjects
Research Focus
4.1 Necessary Content
Instructional Designers,
Training or Education
Managers
Overview of 3SC SDK project
Various groups interviewed identified the following content as
critical to using the SDK.
External Programmers
(experienced and junior
levels)
Observe programmer (without any
Rockwell or call center experience)
as they learn to use the SDK
Instructional support needs and wants
of audience
Documentation of the system requirements.
A comprehensive list of all parts of the SDK.
Instructions on installation.
Definitions of terminology, objects and entities, especially for
terms specific to Rockwell FirstPoint Contact.
One programmer had VB experience;
one did not.
Rapid Application
Developers, Engineers,
Computer Telephony
Integration (CTI)
Application Integrators
Application developer view of 3CS
SDK
IT Support Staff and
their Management
IT support’s view of learning support
systems
Upper and Middle
Management:
Understanding of:
3CS Senior Product
Manager
Customer Contact
Manager
CTI Application
Engineering Manager
Director of Product
Line
Director of Consulting
Services
Strategic Channel
Manager
Marketing Manager
Channel and Technical
Training
Salespeople with SDK
customers
A cross-reference to call center terms used by other companies.
An explanation or demonstration of call center activity and
functions.
Guidelines and directions for using Visual Basic or C++
programming.
An explanation or demonstration of ActiveX technology.
A description or demonstration of types of applications that can
be developed with the SDK.
Business goals of the product
Knowledge available for external
customers
Another SDK learning support
system
Business goals for 3CS SDK
Training and application
development
Systems Integrator’s attitude towards
the SDK
Marketing and business goals of 3CS
SDK
Support material necessary to
facilitate technical training for the
channel partners
Assessment participants felt that the learning content should:
Customer attitude towards 3CS SDK
In-house programmers consisted of two types: existing customers
of 3CS SDK, and potential customers. Interviews produced
surprising information about the intended user’s level of
programming knowledge.
Salespeople with potential SDK customers
Customer attitude towards 3CS SDK
Current cxustomers of
the SDK
Learning support improvements
based on their experience with the
SDK
Potential customers of
the SDK
Learning support improvements
based on their reaction to the
product’s introduction
Focus on how to do things, not necessarily why.
Provide simple samples that can be used in developing
applications.
4.2 Target Audience
There are two distinct target users of the 3CS SDK in the United
States:
In-house programmers employed by customers.
Programmers employed by systems integrators.
It was believed that these two US target groups would have very
different experiences, education and needs.
4.2.1 In-house programmers
Two-thirds of Rockwell FirstPoint Contact’s existing customers
of 3CS SDK were accustomed to its call center terminology and
equipment and were experienced programmers. They were
classified as high-level programmers with a high level of
Rockwell FirstPoint Contact call center experience. Only onethird of the customers interviewed had already completed an SDK
application.
The potential customers interviewed were mainly novice- to
intermediate-level programmers. Programming was usually only a
part of their job. Most had no formal Visual Basic or C++
programming experience. On the other hand, these customers
were already customers of Rockwell FirstPoint Contact, and had a
high level of call center experience. For this group, an orientation
to ActiveX technology was considered important. Also, it was
important to demonstrate specifically how things were done in
What they know about the SDK, as a
potential developer
International Training
and Services Managers
Understand the needs internationally
This paper was first published in slightly different form by ACM.
–4–
This version provided by Gordon & Gordon: http://www.gordonandgordon.com
different programming environments (Visual Basic, C++ or both)
so that they could apply and learn from these samples.
with no call center experience felt comfortable attempting to
develop simple applications.
From interviews with the company’s business and marketing
people, the researchers got this description of the customer enduser:
Rockwell FirstPoint Contact programmers were given 3CS SDK
to develop an application. This group, who until then had not had
any experience with this SDK, were asked whether they thought
call center experience was necessary. They responded:
The end-user works in a call center, is a junior
programmer with 2 years of programming experience in
VB or C++ and possibly some call center experience.
No mention of the call center in the SDK— don’t know how to
relate call center to SDK.
The needs assessment, however, found that the SDK users may be
less qualified programmers than the company expected, or that
customers did not have the correct employees assigned to develop
applications with the SDK.
I had no confusion about call centers because I went through the
sample code.
I learned about call center through using the SDK.
Explanations of objects needed for those who don’t know call
centers.
4.2.2 Systems Integrators
The researchers were only able to talk to one systems integration
(SI) company: Granite Solutions. Accordingly, their report
described systems integrators based on information also provided
by system integration employees of Rockwell FirstPoint Contact:
Some explanation [needed] of call-center-related [objects].
It took [me] two weeks to start feeling comfortable, but you
[really] need six months of Rockwell FirstPoint Contact call
center experience.
Systems integrators employ high-level programmers who develop
applications for third parties or for resale/licensing.
Knowledge of the [overall product] should be a prerequisite for
using the SDK.
Systems integrators will most likely have programmers in their
organizations with programming knowledge in C++ and/or
Visual Basic, but these programmers may or may not have
experience with Rockwell FirstPoint Contact products or
with any other call center technology. (The one SI firm
investigated was not familiar with call centers and needed
guidance during on-site training regarding terminology and
call center architecture.)
The researchers gathered the following statistics regarding call
center experience:
33% of the customer programmers had low call center experience.
100% of the potential customers had excellent call center
experience.
4.3.2 Rockwell FirstPoint Contact Experience
Whether experience with Rockwell Call Center products was
necessary was not clear. Everyone that the researchers talked with,
including customers, had experience with Rockwell FirstPoint
Contact products. (The only exception was programming staff
from Granite Solutions.) It was found that call center terminology
varies from company to company.
The highest-level programmers may not be assigned to work on
the application but might be available for support of less
experienced programmers.
There is a wide range of systems integrators. Some, the
researchers pointed out, will need less initial orientation to the
3CS SDK and/or the programming environment. Ultimately, they
will be interested in more in-depth knowledge (than in-house
programmers), as they will be developing salable or customizable
applications. They will benefit from an introduction to the
features and benefits of the product. Good learning support will
be key for them as they will make or lose money based on the
time it takes them to develop an application.
Here are some of their comments:

Call center language is proprietary. It is not phone system
generic.

Need generic call center knowledge.

Most people work 100% of time on one type of switch, i.e.,
Rockwell FirstPoint Contact, [Competitor X]. Terminology
is drastically different [between competing switches].
4.3 Prerequisite Knowledge
The level of experience needed with call centers, Rockwell
FirstPoint Contact systems, Visual Basic and C++ programming
was examined closely during the assessment.
When Rockwell FirstPoint Contact employees who were actually
developing applications with the SDK were asked about the need
for product-related knowledge about 3CS, Administrator’s GUI,
the switch (ACD), and so forth, they said:
4.3.1 Call Center Experience
To test whether call center experience was necessary to use the
SDK, the researchers worked with Granite Solutions programmers
who had no call center experience.
Observation of these experienced Visual Basic programmers using
the SDK indicated that call center experience was critical. It was
not possible to understand the SDK in its then-current form
without a great deal of one-on-one guidance.
Viewing the current SDK PowerPoint presentation on their own
was not enough to overcome the hurdle of unfamiliar terminology
and architecture. However, after 1.5 hours of instructor-led
training using the PowerPoint presentation, even the programmers
This paper was first published in slightly different form by ACM.
–5–

Knowledge of the [product] is important—should be a
prerequisite for using the 3CS SDK.

Programmers need [product] specific knowledge; call center
experience would help too. Experience [will be necessary for
them] to do it on their own. Will be frustrating for
companies without that knowledge.

Don’t need to know a lot about 3CS [SDK] to use it. Used
the Administrator’s GUI to try to figure out what was going
on behind the scenes. Also used compiled test applications.

3CS is a graphical model of the [switch]. If you know stuff
about [the switch] and you know the entities you are fine.
This version provided by Gordon & Gordon: http://www.gordonandgordon.com
The Administrator’s GUI will help you see what the SDK can
do.

Outside of the USA, there are many programmers for which
English is their second language. For these programmers,
reference documentation and on-line help is the preferred
structure. Instructor-led classroom training is more difficult for
them to learn from because of the speed of speech and the
differences in accents. In reference documentation and on-line
help, plain English without colloquialisms is important.
If you understand the [switch], what is in the programmer’s
reference guide is not too hard to understand.
4.3.3 Visual Basic or C++ Experience
The level of experience with Visual Basic and/or C++ was
considered. All of the company’s client application programmers
were using Visual Basic. When those who were actually
developing SDK applications were asked about the need for
Visual Basic knowledge they said:
4.5 Programmer’s Reference Guide
The first version of 3CS SDK was shipped with a Programmer’s
Reference Guide, a 154-page Microsoft® Word formatted
document written by one of the SDK product developers. About
six pages were devoted to introductory information, including
ActiveX concepts. The remainder of the manual consisted of
documentation of the objects, as well as the properties, methods
and events associated with each object.
Need good knowledge of Visual Basic – intermediate or
advanced. Good knowledge of programming [needed], but
[programmers] with no call center will have trouble too.
Call centers are specialized knowledge. Need that knowledge to
understand [call] flow and make sense of it. Programmers in
telecommunications needed it.
The researchers concluded that much more documentation was
needed: see section 5. Recommendations for details.
Programming knowledge can be minimal, call center knowledge
a must.
4.6 PowerPoint Presentation as Standalone
Document
Note that the first release of the SDK was intended for a Visual
Basic programming environment. While it could be used in other
environments, development focus and support was initially for
Visual Basic.
The researchers gathered
programming knowledge:
the
following
statistics
A Rockwell FirstPoint Contact systems integration manager on
the 3CS SDK project developed a Microsoft® PowerPoint®
presentation that he used to train customers on-site. The
presentation was on the installation CD-ROM so a new user could
view it on their own if they tried to learn the SDK without the onsite training.
about
33% of the customer programmers used the SDK in a non- Visual
Basic/C++ environment.
The remaining presentation topics included:
3CS Architecture.
42% of the potential customers had excellent Visual Basic
programming experience.
COM and ActiveX.
3CS SDK relationships.
57% of the potential customers had low to moderate Visual Basic
programming experience.
Object-oriented (ActiveX) terminology,
properties, methods, and events.
4.4 How Programmers Use Documentation
and Training
as
objects,
3CS entity types, such as trunk groups, ANI, DNIS, applications,
agent groups, agents, and supervisors.
Applications developers want to learn only as they need the
information, the researchers observed. They want need-to-know
information, not nice-to-know information. Because of this, few
users are interested in long tutorials or hours in a classroom. They
want to begin coding immediately and be directed to the specific
help section that answers their specific coding problem.
Details of the 3CS API, such as connecting, getting a collection,
getting an entity, monitoring real-time data, and making
configuration changes.
In sum, the slide presentation contained conceptual and how-to
information that would go typically into a Developer’s Guide (as
opposed to a Reference Manual). The presentation was developed
to deliver on-site to customers. Questions and clarifications were
addressed during the presentation. To use this tool as a standalone learning support, the researchers concluded additional slides
and more information would be needed.
In-house programmers may develop applications intermittently,
putting aside the SDK as other jobs take priority. The 3CS SDK is
probably only a small portion of their job responsibilities.
Additionally, there is a lot of turnover in call centers so that new,
inexperienced people will always be learning how to use the
product. For this reason it is important that learning support be
available all the time in the form of on-line help, Web and CDROM based training, and telephone support. Because these
learners are coming in and out of projects, they may need more
guidance to reorient themselves.
Two programmers at Granite Solutions with no call center
experience viewed the presentation on their own to see if they
could understand the SDK. One of them spent about 10 minutes
viewing the slides. The other spent about 20 minutes. Their
comments were:
Presentation was okay…. Needs more examples of methods,
properties.
Systems integrators, on the other hand, may want intensive
training initially so that a person can dedicate a large chunk of
time to developing applications. They need a greater depth of
knowledge and are more dedicated to developing applications
quickly, because applications are a source of revenue. For this
group, speedy and easy access to the necessary learning support
can be the difference between profit and loss.
This paper was first published in slightly different form by ACM.
such
All terms need to be defined and embellished.
There were… slides that helped a lot: the ones on architecture
and the ones that showed examples.
–6–
This version provided by Gordon & Gordon: http://www.gordonandgordon.com
People that entered an application into a contest had this to say
about the presentation:
was a build that became more complete chapter by chapter, to
develop a complete application.
[The] PowerPoint presentation needs to be one of the tutorials.
Here are comments from programmers regarding these samples:
[The] PowerPoint presentation was more often referred to than
SDK reference guide. Only problem was it didn’t go far
enough. How to get events and deal with them was not
included.

[Samples] were pyramid-like rather than broken into simple
concepts. Hard to follow...embedded too much information
into the sample.
[Samples] are useful when you become experienced, but wasn’t a
starting point. However, would leave example programs that
are there; they will be helpful if you want to do a complex
program.
4.7 Call Center Training CD-ROM
The 3CS SDK shipped with a CD-ROM course on basic call
center concepts; in other words, it contained information on the
domain of the SDK. The course was intended for a wide audience,
not for programmers in particular. It had very good graphics,
audio, animation and instructional design. It was useful for a
person with no call center experience as it explained the most
common terminology and the overall call center architecture (but
not the 3CS SDK) using the company’s own terminology.
4.10 Desired Learning Structures
Whether or not a person is an experienced programmer, the
researchers observed there were some learning structures that
commonly appealed to most programmers. Almost unanimous
was the agreement that programmers will not read manuals from
start to finish but will refer to them if they have a problem.
The programmers at Rockwell FirstPoint Contact did not watch
the CD-ROM but had quite a bit of call center experience. A
programmer at Granite took about 1 hour to view the CD. Some
comments from those who viewed the CD-ROM included:
The researchers asked Rockwell FirstPoint Contact IT employees,
whose job was to provide customer support on software and
hardware issues, about support needs for technical people in
general:
[Course knowledge] testing requires correct answers before you
can go on.
Technical people … don’t like to be challenged on their technical
skills
Can’t get definitions individually – all definitions and screens are
in one pdf file.
99% are mad if they have to ask for help.
If a technical person has a problem he or she would check things
in this order:
No mention of SDK.
4.8 On-Site Training with PowerPoint
Presentation
The researchers observed a one-day training session for new users
of the SDK, in which the programmer who developed the training
spent about 1 3/4 hours running through his presentation. After
this time, the programmers (SDK users), who previously had
struggled to understand the SDK, felt a lot more comfortable with
it. They especially appreciated the slides that explained the
architecture of the various components of the product (including
the 3CS, the 3CS SDK, the Administrator’s GUI, and the switch
itself) as well as the object architecture.
The instructor explained some performance considerations, which
would be important for a programmer to know as well.
The goal of the on-site training was to have the programmers
develop a simple application that can be up and running within a
1/2 a day. After the presentation, the instructor worked one-onone with one of the programmers and within a 1/2 hour had a
simple application developed. He led the programmer step-by-step
through the installation and setup—key areas where the
programmer had trouble doing it on his own.
1.
Go to search directly - need plain text and strings for
key words. If they don’t like a help file, they will never
go [back] to it again.
2.
If more than one person were working on the project,
they would try to get help from them.
3.
Go to manual (if it doesn’t have a date) and look in
glossary. If the manual has a date that is too old, they
will assume it’s out of date and not use it.
4.
Go to user group.
5.
Go to product web site.
6.
Go to company [product] web site.
7.
Call for help - last choice.
The younger programmers just want to soak up information. They
like a self-directed learning environment where they can pick
the information and learn at the level they prefer. The more
experienced people want the information quickly. Both like a
cookbook. No one reads a manual.
Programmers were asked about their own preferred learning style.
Here were their responses:
Actually leading the programmer through the steps involved in
developing the application gave the programmer a lot of
confidence that he could do it on his own.
Context sensitive help (F1): Linking help text with their
development tool. Position cursor and it will jump off to a
help text.
4.9 Code Samples
Include drill down on each event. Gear the learning more for VB
and/or C++ instead of making it generic like it is now. I
would develop in Visual C++ to have more control. Most
users wouldn’t want the sophistication of Visual C++ as [it]
requires more programming knowledge.
A set of sample applications was included on the installation CD
in the initial 3CS SDK distribution. Six of them were Visual
Basic applications, organized in folders labeled Chapter 1 to
Chapter 6., with accompanying README files. The sample code
Have a robust sample set for me to review.
This paper was first published in slightly different form by ACM.
–7–
This version provided by Gordon & Gordon: http://www.gordonandgordon.com
Like to dive right in [don’t read manual] - likes documentation
online with links - used to [online] help in searchable
format.
4.12 Suggestions To Reduce Learning Curve
Want to get updates and patches online.
The goal of the learning support was to have programmers begin
to develop applications within 2 weeks (60-80 hours) of working
with the 3CS SDK. Because most programmers that were
interviewed needed more time than this to be successful, the
researchers asked them for suggestions on how to reduce the
learning curve. Almost universally, the programmers asked for:
Search for a tutorial on a topic. Need to get little jewels. Need a
way to build a little application. No more than 10 lines of
code on an example.
A robust, yet simple, sample set of common useable applications
that includes and documents the code. [Many suggested the
samples have 10 lines of code or less.]
Don’t want a video to educate me.
Samples that are at a production level so customers can just install
and use them.
Online (knowledge bases).
Paper.
The researchers concluded that programmers like to learn by
doing. For example:
Commentary with the source codes explaining why it was done
this way.
They want robust samples that they can use as is, or modify and
incorporate into larger applications. They are not interested
in long tutorials or videos.
Some advanced samples would be helpful (like the one that is
already in the SDK).
They like online help that will get them answers to their specific
questions.
Short tutorials of basic functions, including screen shots and
demonstrations. These would be small, confidence-building
exercises.
They want real solutions to their problems. For example, many
suggested providing codes that they can cut and paste into
their applications.
Context sensitive help (F1) based on text and strings.
A dictionary with definitions and cross-reference to generic
terminology.
4.11 Suggestions for Good Support on a
Product
Documentation for the novice developer who has no experience
with the SDK or call centers. An overview for a nontechnical audience.
Programmers made many suggestions for how to provide good
support on a product, including:
Autorun SETUP. If SETUP]doesn’t work, they will look at the
jewel case insert or Readme file.
5. RECOMMENDATIONS
The first version of 3CS SDK included reference documentation.
The researchers recommended that future SDKs also include:
Insert in Jewel Case: Readme file with setup and installation
instructions, system requirements.
An overview of the SDK and its components.
Uninstall instructions.
Specific steps for installing and using the SDK, which can be
accessed as needed.
Phone number to call for support.
Help tools for understanding and applying terminology and
programming.
Web page address for support.
PDF manual with hyperlinks.
The following tables shows the recommended contents of each of
these three supports and options for providing them:
Windows help file from within VB - with How To’s.
Simple steps to take in programming.
Troubleshooting suggestions.
Tutorials that build an application step by step.
Tutorial on proper way to develop a module so that you can do
error trapping.
5.1 Support
Documentation all online.
Web page support, including:

Error definitions that will actually explain how to
address a problem.

FAQ.

Discussion forums.

Full text searches.

Web pages available from the CD as well as the web.
This paper was first published in slightly different form by ACM.
Contents
–8–
Structure options
This version provided by Gordon & Gordon: http://www.gordonandgordon.com
Contents
Description of SDK
components
Purpose of SDK
SDK’s uses – what it can do
for the customer
Intended users of SDK
Prerequisites for intended
users
SDK limitations
Success stories
Available applications
included with SDK or for
sale or license
Structure options
5.3 Help tools for use with SDK:
Written document, print
and/or electronic formats
Separate CD-ROM multi
media presentation
Microsoft® PowerPoint
presentation
Facilitated presentation
Web-based presentation
Web site
Combination of the above
Contents
Sample code
Glossary with synonyms
FAQs
E-mail addresses, phone
number directory for support
Annotated code and other
libraries
Searchable knowledge base
Technical support
5.2 Specific steps for installing and using SDK
Contents
Narrative and visuals for:
How to’s
What if’s
Examples of well
commented short sample
code (10 lines or less)
Useable applications
Debugging
Where to go for help
Structure options
Written document
CD-ROM resource files
On-line searchable files
Synchronous on-line help
(monitored/facilitated site)
Asynchronous on-line help
(email to trainer/facilitator
with one day max turn
around)
Chat room and discussion
forum for users
The Roles of the Authors
The authors are:
Structure options
Janet Nykaza and Rhonda Messinger, the instructional designers
from Learning Solutions Group, Inc. who led the needs
assessment project on behalf of Rockwell FirstPoint Contact.
Written document
CD-ROM presentation
Microsoft® PowerPoint
presentation
Facilitated presentation
Web-based presentation
Tutorial
Help
Video
Chat room
On-line help
Combination of the above
Fran Boehme and Cherie Norman, the manager and senior
instructional designer from Rockwell FirstPoint Contact’s
Knowledge Center, who were responsible for providing the
documentation and training enhancements for the 3CS SDK.
Matthew Mace, president of Granite Solutions, Inc., who had
been contracted by Rockwell FirstPoint Contact to provide
support for the 3CS SDK documentation and training needs
assessment effort, and ultimately in designing and
implementing the web-based learning support system.
Manuel Gordon, a technical writer and a partner in Gordon &
Gordon, who wrote much of the content for the learning
support that was developed as a result of the needs
assessment.
This paper was first published in slightly different form by ACM.
–9–
This version provided by Gordon & Gordon: http://www.gordonandgordon.com