SIGDOC notes

[Kathleen Nosbisch <kat -at- NETWISE -dot- COM>]

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:

Design:
--content & format
--technical requirements

Implementation:
--key milestones along the way

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

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

Task Profile:
--user tasks
--frequency
--sequence

User Access
 -most important... *no more than 4 levels deep*
--how users move in help
        --access
        --navigate
        --exit
--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

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

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

Implementation:
--storyboarding
--prototyping
--editing
--usability testing
--unit and integration testing
--release plan
--project management

Prototyping:
--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:
--performance
--time
--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)

Mediocre:
--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

Robust:
--non-linear
--chunked topics (in some organization that makes sense to
        user)
--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)
--Accessibility
--Exhaustiveness
--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
KISS
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

-#{\footnoteabc123}
2.title string
${\footnotetopictitle}
3.keywords
K{\footnote keyword1;keyword2}
4.frame string
Z{\footnote ABC0001}

Wordperfect Macros:
Topics:
Prepare
Topic
Link
PopUp
Make RTF
14 pt.line
Records:
newest
topic file
make list

Prepare:
--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

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

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

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

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

+++++

Learnability in Technical Writing
Kathy Haramundanis, from DEC

Learnability - to be learnable, the doc must be:
--legible
--readable
--usable
--learnable
--comprehensible
--understandable
--knowable

Learnability requires all the quality metrics of tech communication:
--accuracy
--completeness
--usability
--clear writing
--readability
--logical presentation
--conciseness
--appropriate language
--grammaticality
--appropriate content and scope
--packaging
--presentation

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

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:
--visuals
--graphics
--illustrations
--video
--sound
--animation

Material that is easy to learn is:
--memorable
--logical
--reconstructible
--consistent
--visual

+++++

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
4.Interviews
5.Surveys
6.System benchmarking
7.Wizard of Oz Technique
8.Guided Interaction
9.Beta-testing

+++++

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
        team
--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
documented?





-end-


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