Writing Help Procedures That Work

Sunday

Leah Guren, Cow TC

1:00 - 4:30pm

Users have come to expect task-based Help topics rather than mere descriptions of product features. They want to know how to accomplish tasks, not just understand interface isolated from the realities of their workflow.

Writing procedures deserves time, thought, and careful analysis. Help authors can follow these best practices throughout the process to create procedures that are more useful, more appealing, easier to follow, and supporting of the needs of the audience.

This workshop includes plenty of hands-on exercises and class participation.

Learning Objectives

Participants will:

• Determine which key tasks need to be documented in the Help system.
• Decide how to link between task-based and feature-based topics to meet user expectations.
• Explore strategies for supporting the needs of different user groups.
• Master best practices for procedures, from top to bottom.
• Gain ideas for simple usability testing of these procedures.

Session Outline

• Intro: The Need for Procedures
• Task-based vs. Feature-Based
• Procedures in Help vs. Other Docs
• Best Practices
• Performing Audience Analysis
• Identifying Tasks
• Intros
• Prerequisites
• Hazards
• Steps
• Layered Info
• Graphics
• Navigational Cues
• Testing
• Conclusion

Enabling Feedback and Collaboration Within Help

Monday

Matthew Ellison, Matthew Ellison Consulting

10:30 - 11:30am

Help for software applications has traditionally provided a one-way flow of information to the user. However, many major software vendors now include mechanisms in their Help that enable users to provide feedback on the value of the information they have just read. It has also become possible for users of some Help systems to add their own comments and annotations, and to share these with other users. In this way, Help is beginning to emulate the collaborative nature of wikis and forums.

But just how useful and effective are these feedback and collaboration features, and how many users actually take advantage of them? And how can you build these features into your own Help systems? This session addresses these questions by using a case study to illustrate the extent to which users take advantage of feedback and collaboration within software Help. It also surveys the range of methods and technologies that are currently available for enabling this kind of two-way communication.

— YOU WILL LEARN —

• How users of software are becoming increasingly collaborative
• About a range of real-life examples of feedback and collaboration systems
• The advantages of a Help system over other collaborative resources such as wikis and forums
• How collaboration can benefit both users and developers of Help
• What tools and technologies are available for implementing feedback and collaboration

The Power of Controlled Language in UA

Monday

Dave Gash, HyperTrain dot Com

12:45 - 1:45pm

Controlled languages use basic writing rules and tightly-controlled vocabularies to make sentences simpler and more consistent. Already widely used in aerospace, defense, and other precision-critical industries, controlled language is finding its way into other technical arenas such as medicine, finance, and of course user assistance. This session introduces you to controlled language and its many benefits, explains how to approach the adoption of controlled language in your UA documents, and looks at some available controlled language software and services. You'll find that controlled language is a logical, accessible technology that can truly make your Help better, faster, and cheaper!

— YOU WILL LEARN —

• Background and concepts of controlled language
• Benefits of using a controlled language
• How dictionaries can be adapted and developed
• What products and services are available

Documentation for Software Engineers - More than Just Code Comments

Monday

Ulrike Parson, parson communication

2:05 - 3:05pm

How to document source code and application programming interfaces for software engineers? "Read the code and you will understand" - but it is not that simple. Code comments may help, but they cannot provide the procedural or background information that engineers need to efficiently work with a programming interface or existing source code. How can technical writers deliver useful documentation to software engineers?

— YOU WILL LEARN —

• How to combine code comments and programmer's guides (cookbooks) to cover different approaches to API documentation
• How to structure information for programmer's guides (use case approach)
• How to integrate software engineers in the documentation development process by working with Wikis
• How to integrate technical writers in the development process

Building Support for Content Strategy from the Grassroots Up

Monday

Lisa Dyer, Lombardi Software, Inc.

3:25 - 4:25pm

Identify tools and tactics to help you find business opportunities. Solve them, and you establish yourself as the organizational expert in information development processes. Use the momentum to build an information agenda and implement a content strategy for your enterprise.

— YOU WILL LEARN —

• Tactics and strategies to discover problems related to information development processes (discover business opportunities)
• Tactics and strategies to deliver solutions for those problems
• Tactics and strategies to build momentum that will ultimately deliver a content strategy and an "information agenda" for your enterprise

The Programming Writer: UA for Hardware and Software Engineers

Tuesday

Jim Causey, Microsoft

9:50 - 10:50am

UA roles provide the best of both creative and technical roles, and nowhere is this more evident than in the work of a programming writer. Programming writers work on the documentation, specifications, and sample code that make engineers successful, and get to work with the best minds and coolest technology in the industry. In this session, Jim Causey from Microsoft will describe the programming writer role, the tasks and work that programming writers undertake, and the skills and experiences you'll need to succeed in this challenging, exciting job.

— YOU WILL LEARN —

• How programming writers work at Microsoft
• Why being a programming writer is one of the best jobs in the world
• The skills you'll need to succeed as a programming writer

Cultural Dimensions of Software Help Usage

Tuesday

Leah Guren, Cow TC

11:10am - 12:10pm

You put a lot of thought and effort into your online Help solutions. But do you take into consideration the way different groups of users actually use Help? For example, do you know if older users can navigate your Help successfully? When localized, does your Help provide what users in other countries want or expect? Are these differences significant, and, if so, how can you best address them? This session provides empirical data, including clips of usability tests and anecdotal evidence.

— YOU WILL LEARN —

• How high- and low-context cultures differ (and how that affects Help usage)
• How to factor in age as a culture
• How to avoid the five red flags of cultural roadblocks
• How to design with linguistics in mind

Dealing with Subject Matter Experts in the Design Process

Wednesday

Kevin Moore, TiER1 Performance Solutions

8:30 - 9:30am

Admit it, dealing with subject matter experts is often a very time consuming and difficult process that sometimes ends up being a waste of time for you and for the subject matter expert. However, gathering data from people who know about your topic and are considered "experts" is a crucial activity and if done correctly can pay big dividends for your project. In this session we will discuss a "research" approach to gathering data leveraging subject matter experts in the process. In this presentation a discussion of the overall data gathering process, methods for gathering specific data, validity / reliability of data, and the application of neuroscience in dealing with SMEs. If you've ever sat in one of these SME meetings and felt highly frustrated then come to this session! Learn how to use an efficient and effective approach with Subject Matter Experts.

— YOU WILL LEARN —

• Why SMEs are so difficult to deal with and how to adapt!
• How to gather information from a SME in an efficient and effective manner
• Using a research methodology to get the most out of your time with a SME

Wednesday

9:50 - 10:50am

You may be hearing "Agile Development" more frequently now, and we technical writers should celebrate! It's a methodology designed to include feature testing and documentation within very short iterations (2-3 weeks), which means documentation is not left until the last minute. Although it is quite a culture shift, we get in on the ground floor. This session is based on my previous experience on a pre-agile team and my current experience on a formal Agile team, which includes:

• Ensuring tech writers are included on Agile teams and assigned tasks for every user story
• Participating in the process and transition by defining acceptance criteria and writing internal reference documentation
• Exploring flexible alternative documentation delivery mechanisms to deliver for each iteration, while authoring for final help or PDF.

Blackbaud implemented an Agile-based development process just over a year ago and gradually over a several-month period brought each of the company's product lines on board. We now have sprint teams covering six overlapping product lines that also often include overlapping releases. The new process brought with it a number of new challenges for the documentation team, but with each new sprint we streamlined our workflow to complement the Agile expectations, and as a result we're witnessing an improvement in our user assistance.

Wednesday

1:05 - 2:05pm

When planning a software documentation project, good project analysis and writing guidelines will substantially reduce your project "prep time," as well as the time spent writing. That means your project will be completed faster, because you start writing content sooner and spend less time on rework. And because the content has a defined structure, your deliverables will be logical and the topics suitable for single-sourcing.

In this session, you'll learn how to quickly appraise a software application and develop your overall project architecture, then use a pre-defined topic architecture to create content. We'll discuss writing methodologies and how to plan for writing in a book paradigm vs. a topic paradigm. These methods can be used by small and large teams, as well as "teams of one."

Example project architecture and writing guidelines will be provided.

Storyboarding is a popular development strategy for elearning, video, and other visual information presentation platforms that can offer many advantages for user assistance projects. Storyboards allow you to map out the content before writing, provide a consistent content analysis structure for all writers, and collect development notes in a central location. Your client can conduct a technical review from the storyboards, giving you feedback and corrections before any writing takes place, while changes are less expensive to make. Using storyboards also can provide a higher quality product because it guides consistent analysis across all software features. Learn the basics of storyboarding, and you can modify the storyboarding forms and process to fit your specific project and staff requirements for each project.

Gathering User Data Through Diary Studies

Wednesday

Rob Houser, Sage

2:25 - 3:25pm

In this session, you will learn about how to plan and manage diary studies. A diary study is a usability research method that has users record their own actions and reactions to particular activities through frequent "diary" entries. Through diary studies, you can gain more insight into the on-going activities of users without having to be located at their site for extended periods of time.

You can use diary studies for everyday user experience research - to create personas, uncover system requirements, to evaluate an existing system (even a competitor's system), and to capture a list of common problems experienced by a particular group of users. Even if you're not responsible for gathering usability research as regular part of your job, you can use diary studies to better understand how and when users refer to the user assistance that you develop and you can use that data to make improvements to how you design and deliver user assistance.

— YOU WILL LEARN —

• When to use a diary study
• What kinds of data you can expect to capture from a diary study
• How to plan for a diary study
• How to capture data from users
• What special considerations you might have when conducting diary studies of user assistance