The Conference for
Software User Assistance Professionals
Produced by:
in association with:
Session Descriptions
- Current User Assistance Trends and Technologies
(Panel of leading panel of leading vendors of user assistance technologies and services) - Any Colour... so long as it is black
(Dr Tony Self) - The Future of Help is Embedded and Dynamic (and Social)
(Julian Murfitt) - Usability Testing: Down, Dirty, and Doable!
(Leah Guren) - HTML5 for Technical Authors
(Sarah O’Keefe) - CSS3 for Help Authors
(Dr Tony Self) - Getting Over WYSIWYG: A Painless Introduction to Structured Authoring
(Dave Gash) - All About Hyperlinks
(Matthew Ellison) - Case Study: Localization in an Agile Environment
(Cecilia Dobner) - Case Study: Help! I Need Feedback. Where Do I Start?
(Colum McAndrew) - Case Study: Chaotic Wiki meets Structured Authoring
(Ulrike Parson) - Case Study: What's Just Enough Documentation?
(Dominic Smith) - Case Study: Mobile UA Best Practices for Business and Enterprise Apps
(Keren Okman and Ines Milewski) - Single-sourcing Your Print-based Documentation
(Sarah O'Keefe and Matthew Ellison) - Needs Analysis for UA Professionals
(Leah Guren) - Case Study: An Integrated Approach to UI and UA Design
(Ray Gallon) - Case Study: Cloud-based Authoring
(Ellis Pratt) - User Annotations with HTML5
(Dave Gash) - Case Study: Single Sourcing to Multiple Media and for Multiple Products
(Karin Dahlgren)
All conference sessions and workshops are presented in English.
Current User Assistance Trends and Technologies
Panelists include:
Rachel Potts (ISTC)
Mike Hamilton (VP, Product Evangelism, MadCap Software)
George Cristian Bina (Managing Partner, SyncRO Soft - <oXygen/>)
Dennis Crane (CEO, Dr.Explain)
Chaired by Leah Guren (Cow TC)This lively panel session will explore a range of key technology trends and challenges that are facing today's user assistance professionals. There will be an opportunity to put questions to the panel from the audience.
Any Colour... so long as it is black
Henry Ford revolutionised car manufacture when his production line replaced the method where cars were hand-made by artisans. Famously, Henry Ford offered the Model T in "any colour... so long as it is black". There are parallels in technical communication. Many technical communicators are still clinging to hand-crafted documentation, creating custom layouts and "tweaking" formatting, when new modular methods are vastly more efficient. The age of offering documents in any "colour" the customer wants is over. And just as car manufacture has long since moved to automation, technical communication too must embrace automation, with XML providing the technology platform to make this possible.
You will learn:
- How car manufacture can be an allegory for the technical communication profession
- How the car industry coped with transformational process engineering
- What dangers may lie ahead for technical communicators
- Why increased efficiency in documentation does not necessarily mean reduced quality
The Future of Help is Embedded and Dynamic (and Social)
The User Assistance community has been discussing leveraging the user community as contributors, and having Help content treated more as ‘part of the product’, and not an afterthought.
‘Embedded’ Help is user assistance that displays directly inside products—set inside a software UI or displayed through a display panel on a hardware device like a printer LCD or in-car data display. Although there are many benefits to this approach, having to prepare Help for embedded display, in electronic user assistance (CHM, Eclipse and web), and often print presents quite a challenge to the authoring team responsible. And what about user-generated content?
You will learn:
- The challenges and benefits of embedding Help for users and authors
- About effectively single-sourcing for embedded display inside products and other formats
- How to prepare for user contributions at the same time
- How standards like DITA make this single-sourcing and delivery easier and more cost effective
Usability Testing: Down, Dirty, and Doable!
You understand the importance of usability testing for a product's success. You may have even been involved in some way in a product usability test. But are you currently conducting basic usability testing of your Help system? Perhaps you think that it will be too expensive and time-consuming, or that you need to hire a special consultant. Maybe you want to do it, but don't know how to sell the idea to management. Well, never fear! Usability testing can be done on a very small budget and in a lot less time than you may think.
You will learn:
- Basic concepts and terminology of usability testing and how they apply to Help
- Key tasks in the high-level procedure of usability testing
- How to avoid the most common mistakes
- How to interview testers more effectively
- How to interpret results
HTML5 for Technical Authors
This session provides an introduction to HTML5 and discusses how the technology might fit into technical authoring efforts. You will see examples of the new HTML5 markup, learn about the state of browser support for HTML5, and explore the connection between HTML5 and mobile content. The session will also include a discussion of output options and explore the relationship between HTML 5 and XML.
You will learn:
- Important new tags and features available in HTML5
- What distinguishes HTML5 from previous versions of HTML
- What HTML5 offers to technical communicators
- Whether HTML5 is right for you
CSS3 for Help Authors
Many of the limitations that Web developers and Help authors used to criticise CSS for have been eliminated in the latest version of the W3C standard. The usefulness of CSS now extends well beyond formatting Web pages to page layout. Multiple columns, embedded fonts, conditional rules, speech style, and template layouts are some of the powerful enhancements in CSS3. With this new power comes responsibility! We need to understand how to use CSS3 wisely. And taking advantage of CSS wisely means reducing development and maintenance costs. In this session, we will review the new functionality through demonstrations.
You will learn:
- The underlying principles of Cascading Style Sheets
- What new features have been introduced in CSS3
- Which browsers and other processors support CSS3
- Which Authoring Tools support CSS3
- What future lies ahead for CSS implementations
Getting Over WYSIWYG: A Painless Introduction to Structured Authoring
Today, many writers must give up visual control of their content and work within fixed, often restrictive, environments in the name of "Structured Authoring". But why is this, and what's in it for the authors? This session lays out the basics of Structured Authoring and examines its benefits, requirements, and pitfalls to give you a clear grasp of concepts and techniques before you dive into tools and technologies. Specifically, we'll look at the advantages Structured Authoring can bring to individual authors, writing teams, and companies, so you'll soon think of Structured Authoring as your new best friend!
You will learn:
- The rationale and concepts behind Structured Authoring
- Strategies and processes that support Structured Authoring
- How Semantic Markup and Structured Authoring fit together
- How to get started with Structured Authoring
All About Hyperlinks
It has been said that getting user to your content is all about Search Engine Optimization, and that getting users to stay in your content is all about effective linking. This presentation examines the critical (and often overlooked) subject of hyperlinks. It discusses why hyperlinks are so important, and the various ways in which your users might benefit from them. We'll also look at the usability of links, where best to place them, and how to word them. We'll look at a variety of possible linking strategies for ensuring that users do not miss the critical information that they need, and yet are also not diverted unnecessarily away from their key information needs. Finally, we'll weigh up the pros and cons of using keyword-driven links (as in the form of ALinks, "See Also" controls, and the other specialist Help controls provided by some of the Help Authoring Tools), and we'll consider the potential of "soft linking", an emerging technique that makes hyperlinks easier to create and maintain.
You will learn:
- When and how users actually follow hyperlinks
- How to make it easier for users to select the most relevant links for them
- How to ensure that your hyperlinks don't take your users off-track
- When it makes sense to use keyword-driven links
- What are soft links, and how they might be relevant to software user assistance
Case Study: Localization in an Agile Environment
Cecilia Dobner (Autodesk)
The Agile Manifesto welcomes changing requirements throughout the entire project cycle; it promotes shorter timescales and is based on face-to-face conversations of self-organized teams. But what does all this mean to Localization? Traditionally, Localization has worked with its counterparts to promote precise planning and scheduling and stability of source code and doc content; how can Localization work with an Agile Development environment and even take benefit from it? Autodesk Localization Services (LS) has been working for the past nine months on developing an Agile Localization approach — collecting information on how the development teams are applying Agile, and defining Localization strategies based on continuous development and continuous translation.
You will learn:
- How Autodesk LS relates to Development teams
- Which are the points of contact between Autodesk LS and Autodesk Dev teams
- Autodesk Localization Services workflow samples
- What are the opportunities for localization in an Agile environment
Case Study: Help! I Need Feedback. Where Do I Start?
Getting user feedback on documentation is a hot topic for Technical Communicators. It causes much soul searching on how best to achieve it. In this session, we'll describe how Adobe RoboHelp Server was implemented at IDBS to complement our existing Adobe RoboHelp documentation. We'll explain how this helped us to identify areas where our documentation could be improved. The session will also demonstrate how Adobe RoboHelp Server highlighted areas where our application's interface and usability could be further improved.
You will learn about the:
- Feedback options considered by IDBS
- Positives and negatives of implementing Adobe RoboHelp Server
- Adobe RoboHelp Server’s reporting capabilities
- Usability, UI and help changes implemented
Case Study: Chaotic Wiki meets Structured Authoring
Wikis are old, and so are the problems that wiki authors and readers struggle with. Collaborative authoring in wikis might tap new synergies but often the outcome is as chaotic as a humming beehive. So how can you structure your content? How can you make it accessible? How can you organize reviews and input supply?
Technical writing had to deal with these problems before and found one answer in structured, XML-based authoring. This presentation shows a solution for structured authoring in a wiki by using additional metadata and forms. The case study is based on a MediaWiki enhanced with the open-source Semantic Bundle extensions. We will demonstrate how forms enable writers to structure their content in a DITA-similar way in topic types such as task, reference, and concept. We will also demonstrate how metadata is used to enhance content navigation and access to information, as well as to manage an authoring and review workflow.
You will learn:
- How to realize structured authoring in a wiki
- How to enhance content navigation and access to information by means of semantic information
- How to use metadata to improve your workflow and collaboration with developers
Case Study: What's Just Enough Documentation?
Dominic Smith (Red Gate Software)
The Lean Startup movement has taken Silicon Valley by storm. Eric Ries describes how teams working on new products in uncertain markets can learn by practising very fast iterations to gather actionable data from users to guide further development. The Runtime Analytics project at Red Gate is using this approach to develop such a product.
Technical Authors at Red Gate have always been more involved with development projects than at many companies, and our focus on embedded assistance and strings, rather than manuals, is vital when working on such projects.
In this presentation, I give some practical advice based on over six months’ experience authoring in a Lean Startup environment. What does Minimum Viable Documentation look like? Should you experiment with embedded UA? What happens if you have multiple ‘latest’ versions of the product? And crucially, how can we best offer user assistance when working so rapidly?
You will learn:
- How Lean Startups can minimise waste and risk by running quick experiments to gain data from users
- What problems are caused for user assistance by frequent iterations of the software
- What is the minimum level of user assistance that we should focus on initially?
- How should we add to this initial user assistance based on users' questions and feedback?
Case Study: Mobile UA Best Practices for Business and Enterprise Apps
Keren Okman and Ines Milewski (SAP)
Producing quality user assistance (UA) for business and enterprise apps can be tricky. More often than not, the UA for such apps must tie into the UA considerations of other apps or even an entire suite of products. To avoid complexity while enhancing usability, you can implement best practices that keep it SIMPLE: Scalable, Intuitive, Multi-Platform, Legal, and Extensible. The presentation covers best practices for the entire product lifecycle, from idea to download.
You will learn:
- Do’s and don’ts for the UA of business and enterprise apps
- Innovative ways to quickly produce mobile UA at a low cost to the organization
- Best practices for using people-centric language and dealing with translation and localization constraints
- Tips and tricks for achieving ongoing improvement of the UA through social networks and customer co-innovation
Single-sourcing Your Print-based Documentation
(or How to Generate Good PDFs)
Sarah O'Keefe and Matthew Ellison
As user assistance developers, we are often called upon to generate print-based documentation (usually PDF files) from the same content source as we use for our on-screen Help. And this is a challenge not only from a technical point of view, but also because the expectations of our end-users for on-screen Help and for print-based documentation are often completely different.
This session explores a range of tools, techniques, and best practices for generating effective and professionally formatted PDFs from a single source. In the first part of the presentation, Sarah O'Keefe shows how to set up a PDF/print publishing workflow for a DITA source, and discusses the advantages and disadvantages of using various tools including the DITA Open Toolkit and Adobe FrameMaker.
In the second part of the presentation, Matthew Ellison surveys the support for print-based output that is provided by today's leading Help Authoring Tools. He explains the different workflows used, and assesses the strengths and weaknesses of each approach.
You will learn:
- How print-based documentation is used differently from screen-based user assistance
- Key design consideration for print-based documentation
- The advantages and disadvantages of using a pure XML solution such as DITA over a Help Authoring Tool
- How to set up a PDF/print publishing workflow for a DITA source
- How each of the leading Help Authoring Tools supports print-based output
Needs Analysis for UA Professionals
Do you confidently update your product's Help but struggle with projects that require ground-up development? Sometimes, figuring out what you need to create can seem like an insurmountable obstacle!
This session covers the basics of performing needs analysis, the process of determining what exactly has to be documented in the Help, and how. This is also an important component in estimating and budgeting.
You will learn:
- Handy shortcuts for starting the analysis
- The importance of identifying the main content categories
- How to use personas as a cyclical analysis
- How to map user workflow to task analysis
- How to use the analysis results for project estimation
Case Study: An Integrated Approach to UI and UA Design
Ray Gallon (Culturecom)
This case study shows how a call to produce "documentation" can lead to a complete informational subsystem design. The subject is a new application for Business Activity Monitoring that is aimed at two distinct audiences, needs two different voices, and requires two different approaches both in the interface and in the user assistance.
Ray will describe his experience of being closely involved in almost every aspect of the informational design: interface, software content and user guidance. Techniques employed to create layered user assistance include rich tool tips, a pop-up Help page with direct links to tasks, and a full classic tripane Help system. Also included in the project is the idea of customisable help at two levels: in-house consultants will be able to write modules oriented to a specific client, and end-users will be able to annotate any help page.
You will learn:
- How the needs of user assistance invariably pull us into interface design
- How to integrate multiple disciplines (IA, content strategy, UX, etc.) into your work as a technical communicator
- About the role of language in UI design
- How to use UI design tools (user stories, personas, etc.) for user assistance
Case Study: Cloud-based Authoring
One of the most popular developments in computing in recent years has been the emergence of cloud-based computing and Software as a Service (SaaS). So is technical writing likely to move to the Cloud? In this presentation, we look at how we implemented a cloud-based authoring solution as a way of getting developers to participate in the authoring process.
You will learn:
- Why you might consider adopting a cloud-based solution
- How to implement a cloud-based solution
- The different approaches and services available
- Lessons learned from the project — what worked and didn't work
User Annotations with HTML5
Way back in the olden days (circa 1995), users could add their own annotations to RTF-based WinHelp. Then along came HTML-based help, soon followed by WebHelp, and user annotations became practically impossible to implement. But with HTML5's local storage feature, user annotations are once again a practical and useful content-enhancement device. This session explores local storage and shows how your users can add their own notes to your WebHelp topics or Web pages. We'll see how to save and load user annotations, persist them across sessions, associate them with individual pages, and even share them among pages. After all these years, annotations are back, baby — and better than ever!
You will learn:
- How the HTML5 localStorage object works
- How to save and retrieve user annotations
- How to associate annotations with specific pages
- How to add an attractive annotation area to your pages
Case Study: Single Sourcing to Multiple Media and for Multiple Products
Karin Dahlgren (QlikTech)
When documenting software, it is common to handle the same or similar information in different authoring tools, based on output. For example, FrameMaker may be used for production of pdf files, and RoboHelp for help file creation. It then becomes necessary to update in both places when releasing a new version of the software.
From a company’s point-of view, conversion into a single source project implies benefits such as reduction of training needs for technical writers, and fewer tools to keep up-to-date and pay licenses/ maintenance for. If not before, introduction of localized documentation highlights savings that can be made by reusing information.
As a technical writer, single sourcing provides other advantages as well. Generally, tech writers are fans of structure and order, and this is an opportunity of a lifetime to clean up legacy files and rethink how documentation is organized. Structures that may once have worked well, may no longer fit software/products that have evolved.
You will learn:
- Some traps to be avoided when creating a single source project
- What items to consider when producing output to different media
- On what level to establish conditions
- What kind of information is suitable for different outputs
