SIGDOC notes

Subject: SIGDOC notes
From: Kathleen Nosbisch <kat -at- NETWISE -dot- COM>
Date: Thu, 4 Nov 1993 10:40:39 MST

Ok people, I promised it, so here it is.... notes from SIGDOC....
Hope at least *some* of it is relevant. Feel free to email me any
of your comments, flames, etc... but remember... these are only the
notes I took during the conference sessions, not the complete
presentations; but I *did* write as fast as I could! :)


Following are my personal notes (given as part of a presentation upon
return to work) of the ACM SIGDOC '93 conference. I only
transcribed notes from those sessions that directly affect my work at
Netwise; and was very vague in those places that were covered in
depth in the conference Proceedings.

To get info about joining ACM SIGDOC, (Special Interest Group for
Documentation), contact:

ACM Member Service Department
P.O. Box 12115
Church Street Station
New York, NY 10249
phone (212) 626-0500
fax (212) 944-1318
email:ACMHELP -at- ACM -dot- ORG


Brief Notes from SIGDOC sessions follow....
(+++++ signifies the divider between conference sessions)

From Ground Zero to Multi-Media Product Support
by Mimi Saffer & Dee Stribling from SAS Institute

Part 1: Strategy for Implementation
Part 2: Analysis of Transitions & How to Cope with Changes

Reasons to go online:
--better customer support
--customer demand
--the need to remain competitive

Stages of Implementation:
Stage 1 - Research
Stage 2 - Online versions

Do a Usability Questionnaire with your Customers to get input about
the usefulness of online doc and the desire for it.


One Proven Methodology for Designing Robust Online Help Systems
Angela Patrick & Andy McGurgan from Mead Data Central

Why Design Online Help?
--software more complex and user needs extra guidance
--users have little time for training
--online help can enhance ease of use

Why Traditional Design Methods Don't Work
--online systems are not books
--additional documentation decisions:
--how to chunk info (topic)
--how to link topics
--how to integrate help with application
--software/hardware environments

Do an Online Help Plan on paper, authored by lead writer, approved
by product team and writing team, to be used as a guide throughout
the project. It should contain the following:

--content & format
--technical requirements

--key milestones along the way

--project overview
--documentation business objectives
--components of the doc set
--user profile
--user environment
--task profile
--user access
--detailed outline
--screen format

Interface Standards and Screen Design:
--menu bars
--dialog boxes

Task Profile:
--user tasks

User Access
-most important... *no more than 4 levels deep*
--how users move in help
--help hierarchical scheme

Detailed Outline:
--outline of help topics
--answers to questions
--organized in hierarchical format
--answers to questions

Screen Format:
--help screen location & size
--scrolling and paging
--font size & type
--appealing & consistent look and feel

--provide visual clues on system use
--enhance look of help screen
--link/indicate topic type(s)
--instill feeling of simplicity with the user

--responsible for bug fixes, performance improvements, feature
--maintenance information
--source files
--help interface
--source code control

--usability testing
--unit and integration testing
--release plan
--project management

--first software implementation
--first review of help design
--navigation model
--shows classes of information
--shows design and attributes of screens

Upgrade Skills of Editors:
--industry standards
--basics of screen design

Usability Testing:
--levels, etc.

Online Help Process:
--method for implementing the plan
--guides the team
--supports interactive development
--requires rigorous review of plan
--accommodates change during the project life cycle

Augmenting the Plan & Process:
--online help standards
--text templates
--reuse libraries whenever possible
--authoring tool requirements

Mediocre vs. Robust Designs: (signs of each)

--single level TOC
--system rather than task orientation
--limited use of formatting
--limited access within help
--lack of user perspective
--limited use of text formatting
--no link to associated topics

--chunked topics (in some organization that makes sense to
--text attributes to help users scan
--multi-level TOC
--user oriented perspective
--icons to grab readers' attention
--robust keyword searching
--link to previous level
--link to related topics
--two-column format enhances scan-ability
--user and action-oriented text
--concise, job-specific topics
--use graphics to:
--identify topic type
--limit text
--task focused


Online Help for Windows
by Jean-Marie Comeau & Peter Miller

Access to inline documentation so developers and maintenance people
don't need paper docs. (Inline means entire manual, in this context)
--Accuracy/ease of maintenance

Accessible through the menu bar on Windows, context-sensitive
Passive Help Component - done with Windows help engine, with fields:
--floating tool bar
--Immediate Help
--<screen name> general context information on current screen
on display
--What's this? specific details on current data entry field (as
identified by cursor)

Book-Like Help:
-contents access to the help TOC
-about tombstone data/history on screen (e.g., maintenance
& update notes, etc.)

Language - dynamic switching

Change Request Facility
--captures & stores in a text file
--personal notes
--communicate notes across net, etc.

Tutorial Capability

Windows s/f development kit for help

Steps When Building Help:
1.Prepare the topics
2.Define links and keywords
3.Define style
4.Enter text and code
5.Save in rich text format (RTF)
6.Edit RTF files
7.Add files to project file (HPJ)

--get right to the point, minimalistic writing
--no more than you can see at a glance - brevity
--be able to go straight to top menu
--no more than half dozen links

Stylistic issues:

Headings 14 pt. font
text 12 pt font
no bold
use bullets sparingly, as screens can change
declaration at beginning of each topic:
--what topic is
--what frame belongs to
--what keywords
--specific format it must follow

Help topics:
--each topic has a declaration
context string identifies the topic

2.title string
K{\footnote keyword1;keyword2}
4.frame string
Z{\footnote ABC0001}

Wordperfect Macros:
Make RTF
14 pt.line
topic file
make list

--work in a temporary directory away from main program (don't
name it temp!)
--3-letter prefix defines file name, HSR help source file
--project file
--topic number & title

underline from RTRF defines links.
{\ULdb ...}

--underline for this
--convert files
--edit RTF files

automatically indexes
*macros are available via public domain for these *

Other Issues:
--project management and co-ordination of activities between
programmers & tech writers
--benefits of early involvement of tech writer in project
--in-house resource: business function expertise vs. writing


Learnability in Technical Writing
Kathy Haramundanis, from DEC

Learnability - to be learnable, the doc must be:

Learnability requires all the quality metrics of tech communication:
--clear writing
--logical presentation
--appropriate language
--appropriate content and scope

Memorable - easy to remember:
--if your procedures are hard to follow, they are probably not
--use pointers (x-ref) to another section for more detail if

The user should be able to reconstruct a procedure or task without
referring to a checklist or worksheet:
--what is reconstructible doesn't need a checklist
--material that is consistent presents displays, requires moves
that are the same from one part of the system to another

Information should be visual or visualizable with:

Material that is easy to learn is:


Software Usability - Choosing Appropriate Methods for Evaluating
Online Systems and Documentation

Brad Mehlenbacher, North Carolina State Univ.
Testing your Doc for Usability - Myths & Methods

Testing for Usability - beta tests
1.Identify users and tasks
2.Prepare the equipment & materials
3.Establish a scenario
4.Begin the tasks
5.Compile and analyze the data
6.Debrief the user

9 Usability Methods
1.Talk-aloud protocols
2.Videotaped sessions
3.User-log analyses
6.System benchmarking
7.Wizard of Oz Technique
8.Guided Interaction


Quality and Documentation
Doann Houghton-Alico, Technical Information Associates (TIA), Denver

Doann's company assists businesses and doc departments obtain the ISO
9000 standards certification and the Baldridge award. Her number is
303-321-2122, fax 303-322-1895.

ISO 9000 certifications gives a strong competitive advantage

--a relational database is good for document control
--have reviewers provide complete info for revisions (state that
they must do this in their directions or it will be returned)
--develop icons for your department

her quote: "With documentation, consistency is next to Godliness."

a cross-functional team is most effective

--team handbook - deals with problems of a cross-functional
--do a needs/use analyses when beginning a project

It takes 18 months to 2-3 years to implement a quality system unless
you already have a system in place

--results in fewer returned products, better quality products
and services

ISO 9000 - Motorola, AT&T, Univ. Card Div. have reports of how it
improved their market share

Do a Quality Audit
--ask yourself -am I really documenting what needs to be


Kathleen Nosbisch Netwise, Inc.
Technical Writer 2477 55th Street
kat -at- netwise -dot- com Boulder, Colorado 80301

Previous by Author: Re: How Much?
Next by Author: Typefaces discussion
Previous by Thread: Re: Typeface Info
Next by Thread: Re: Times Roman 'N' Helvetica

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

Sponsored Ads