The Conference for
Software User Assistance
Professionals
Produced by:
in association with:
Session Descriptions
On day 1 of the conference, one of the two optional session tracks will focus on DITA.
Jump to list of sessions in DITA Track.
All conference sessions and workshops are presented in English.
List of general sessions
- Make your content more findable when users browse and search (Tom Johnson)
- Creating video tutorials for user assistance (Tom Johnson)
- Spell it out: the singular story of English spelling (David Crystal)
- Context-agnostic writing for re-use (Dr Tony Self)
- Writing UA for mobile devices: best practice in a continuously evolving world (Rachel Johnston)
- Seldomly Asked Questions (SAQs) (Dr Tony Self)
- Going beyond tasks: creating a workflow path (Leah Guren)
- Content editing: finding the sweet spot between minimalism and fluff (Leah Guren)
- Adopting a wiki-based authoring process (Brian Harris and Dominic Smith)
- Ensuring that we answer our users' real questions (Matthew Ellison)
- Enabling user comments and feedback in user assistance (Matthew Ellison)
- Optimising global documentation development (Bridget Khursheed)
- Applying cognitive science to user assistance (Ray Gallon)
- User assistance is product marketing (Rachel Potts)
- Content delivered? Check. OK, how do we use it? (Colum McAndrew)
- Semi-automatic localization of screenshots (Dr Adrian Morse)
- Agile documentation: delivering in 2-week cycles (Dobrinka Stefanova)
- HTML5: not just for geeks any more (Dave Gash)
List of sessions in DITA track
- Dynamic DITA delivery for Help (Chris Despopoulos)
- Adding custom HTML features to DITA (Dave Gash)
- Using indirect linking for componentised Help (Priscilla Buckley)
- DITA Question and Answers (Q&A) (Panel moderated by Dr Tony Self))
General sessions
Make your content more findable when users browse and search
Users tend to search Help material when they have a specific question they're looking to answer. In contrast, users tend to browse Help material when they don't know exactly what they're looking for. Browsing often leads to better searching, and more searches often lead to better browsing, since the two activities inform each other. How can you make your content easier to find when users either search or browse for information? Answers to this question can span a range of best practices, from understanding search algorithms to including the right metadata, grouping similar topics together, adding related content, and more.
You will learn:
- Why searches often fail in Help material
- How to avoid overwhelming users with too many options
- Why Help material often doesn't include the answers users need
- Tips for organizing content based on principles of information architecture
- How to more closely integrate search and browsing activities
Creating video tutorials for user assistance
Next to Google, YouTube is the second most popular search engine on the web. The popularity of video, especially for how-to scenarios, suggests that it should play a more prominent role in user assistance. However, creating videos poses a number of challenges. Writing a conversational script, recording professional sound, showing crisp screen images, and integrating video into your online help can be tricky. Additionally, in agile environments, video tutorials often have a short shelf-life — remaining current only until the next release. When you create videos, therefore, you have to create them inexpensively and quickly. At the same time, you must maintain a high quality for the visual display and sound.
You will learn:
- How to set up a microphone and recording equipment
- How to write a conversational script that will work well in a three-minute video
- How to get professional sounding voice without hiring a voiceover pro
- How to incorporate learning techniques to increase the effectiveness of the videos
- How to integrate video into user assistance in a way that complements written Help
Spell it out: the singular story of English spelling
Why is there an 'h' in ghost? William Caxton, inventor of the printing press and his Flemish employees are to blame: without a dictionary or style guide to hand in fifteenth century Bruges, the typesetters simply spelled it the way it sounded to their foreign ears, and it stuck. Seventy-five per cent of English spelling is regular but twenty-five per cent is complicated, and in his latest book Spell It Out, the UK's foremost linguistics expert David Crystal extends a helping hand to the confused and curious alike. He unearths the stories behind the rogue words that confound us, and explains why these peculiarities entered the mainstream, in an epic journey taking in sixth century monks, French and Latin upstarts, the Industrial Revolution and the Internet. By learning the history and the principles, Crystal shows how the spellings that break all the rules become easier to get right. In this session, David presents his personal highlights from the book.
Context-agnostic writing for re-use
In the field of technical communication, there is a migration (driven by the need for efficiency) from style-based, document-centric writing approaches to topic-oriented, modular authoring writing techniques. One of the challenges of working within a modular, structured, semantic authoring environment is the imperative to remove context from the writing to enable re-use. In a modular writing environment, a single source or repository of topical information modules are assembled into different publications for delivery in different reading formats. The ability to re-use the same content modules is especially important for organisations managing large documentation suites, such as motor vehicle manufacturers producing documents with sizable proportions of common content. This session argues that by adopting context-agnostic writing techniques for topic-based modular documentation, technical writers can improve content re-use and achieve greater efficiency through the technical documentation life cycle without significantly compromising quality.
You will learn:
- About the principle of separation of content and form
- How to extend the principle to also separate context
- What context-agnostic techniques can be used
- How removing context affects comprehension
- What efficiencies can be gained by context-agnostic techniques
Writing UA for mobile devices: best practice in a continuously evolving world
The proliferation of mobile devices presents a triple challenge to technical communicators. We may be required to document the devices themselves, we may be required to document applications that run on one or more mobile platforms, and we more and more often need to deliver content that can be viewed on mobile devices. The way we interact with technology is changing all the time — and the rate of change shows no sign of slowing down. What does this mean for technical communicators?
In this presentation we'll look at these challenges in more detail and consider what best practice looks like, through a series of real-life examples.
You will learn:
- Why traditional information design may not work for mobile UA
- Moving to mobile: how to develop your mobile strategy
- Characteristics of good (and bad) mobile UA
- How to make "ultraminimalism" work in real life
Seldomly Asked Questions (SAQs)
Frequently Asked Questions (FAQs) have become so common in Help systems and support Websites that the initialism has entered the vernacular. But are FAQs more a convenience for authors than a useful tool for readers? Do FAQs encourage "maximalism" by making it easy for information to be dumped into an unstructured bucket? Are FAQs really frequently asked, or are they more often SAQs — Seldomly Asked Questions? In this presentation, Tony Self takes a light-hearted approach to the topic, but discovers that there are serious questions that we need to ask ourselves.
You will learn:
- When to use FAQs in your content
- What type of questions are best to include
- What type of questions you should avoid
- About the balance between too much and too little information
Going beyond tasks: creating a workflow path
In this session, learn to analyse users' needs beyond the basics. Even task-based Help systems fall short when they do not recognize how real users actually use a product by combining individual tasks into useful workflows. This workshop presentation shows you how to identify typical multi-task user workflows for your product. This will enable you to make the connections that turn "so-so" Help into superb user assistance.
You will learn:
- How to analyse true documentation needs for your products
- How to create scenario-based content
- how to transition from features to tasks to workflows
- How to make valuable connections between ideas
Content editing: finding the sweet spot between minimalism and fluff
Most people understand that online content has to be even less wordy and more streamlined than the content from typical user guides or manuals. But how much cutting is too much? Where do you cross the line from fluffy writing to uselessly terse topics? How do you find the balance? This practical and interactive workshop session will answer these questions.
You will learn:
- How to perform triage on information (the Minimalism Test)
- How to conduct an iterative edit to remove non-essentials
- How to find alternate options for offloading intermediate information
- How to test your solutions
Adopting a wiki-based authoring process
Brian Harris and Dominic Smith
The tech comms team at Red Gate maintain several hundred pages of content on their Support Center, which is supplemented by articles written by the Support team. For several years tech comms have wanted to update the structure of this content to address some usability failings and replace our authoring tool. Doing this only required us to: persuade the management team of the value of this project, get some advice on possible solutions, evaluate the new tool, run an off-site day to review use cases and redesign the structure of our content, train the authors, plan, migrate the hundreds of pages of old content into the new structure, run UX tests, work with support to develop a new workflow, automate some of the processes, plan, plan some more and attempt to stay sane throughout. The result launches in March 2013.
You will learn:
- How to determine requirements and evaluate options for possible solutions
- How to plan the project by breaking it down into sensible phases and get buy-in from senior management at each phase
- How to reorganize all existing content into a consistently structured TOC
- How to train the tech comms team to write in a new tool and migrate a sensible amount of historical existing content to a staging site
- How to involve other parts of the organisation (dev ops, user experience and support) to deliver the migration
Ensuring that we answer our users' real questions
Many users of software choose to seek answers to their questions by using Google to search the Web rather than referring to the online Help provided. One of the key reasons for this is that many Help systems do not address the real-life problems and issues that matter most to users. So how do we find out what is important to our users, and what strategies should be use for including this information in our user assistance? This session answers these questions by covering a range of research methods; it also addresses the question of whether our role is changing from author to content curator.
You will learn:
- About some of the most important potential weaknesses of Help systems
- How to find out the real-life questions that users ask asking about your products
- How to answers these questions in the best possible way
- When (within the development/release life cycle) is the best time to write your user assistance
Enabling user comments and feedback in user assistance
With the Web becoming increasingly collaborative and social, this session looks as possibilities for building a community around your user assistance. We'll discuss the advantages of enabling your users to provide feedback, and suggest ways in which these comments can be used to improve your user assistance. We'll also consider how implementing other social web techniques (such as comments, likes, and votes) can help to engage users with your user assistance. The session provides an update on the latest feedback and collaboration technology available from Adobe, MadCap Software, and other software vendors. These options include a number of free applications such as Disqus and IntenseDebate.
You will learn:
- Simple and cost-effective techniques for enabling users to provide feedback on your user assistance
- How the major authoring tool vendors implement feedback solutions
- Whether the future of user assistance is collaborative and social
- How to add social features to your user assistance
Optimising global documentation development
KAL is a global software company dedicated solely to multi-vendor ATM software. KAL's product suite enables ATM hardware, software and services sourced from multiple vendors to work together perfectly. This allows banks including Citibank, UniCredit and China Construction Bank to adopt a best-of-breed strategy, reduce costs, increase functionality and provide an enhanced customer experience.
KAL is a continuously available company with offices in five different time zones and a multi-lingual workforce. KAL authors work to the same principle and have developed a quick-footed documentation development and delivery approach that never sleeps. However the documentation team is small and geographically disparate. This case study shares our insight into optimisation for global teams, best practices and promotion of collaboration without compromising independence.
You will learn:
- Key strategies for working with disparate teams
- The benefits of collaboration versus independence
- A range of best practices
- How to exploit novel communication methods
Applying cognitive science to user assistance
The Transformation Society is a new research and training organization in Barcelona, Catalonia, that Ray founded together with Dr. Neus Lorenzo, specialist in international education. Over the last year, it has been working on applications of cognitive science to User Assistance. Our colleagues in professional training already use this — why aren't we doing it?
Start with the notion that users are learners. Users faced with urgent tasks have different learning needs than a participant in a training course, but they still need to learn.
In this presentation, Ray outlines some basic principles derived from cognitive science, and demonstrates how to apply them to user assistance to facilitate users' acquisition of mastery of software products. He will also show how we need to break down the separation of conceptual and procedural information, and how we can do this and still maintain integrity of structured writing systems like DITA.
You will learn:
- Basic cognitive concepts: levels of competency, and how humans learn
- How to apply these principles to user assistance
- Why we need to break some long-held sacred rules of technical communication to improve effectiveness
- How DITA and other structured writing tools can be adapted to these ideas and still maintain the advantages of structure
User assistance is product marketing
Getting user assistance right for development platforms and tools is difficult. Creating effective marketing content for development platforms and tools is difficult. Caplin’s new website does both, with the same set of content.
In 2012, Caplin were repackaging their development platform product as a series of separate tools. At the same time, they were keen to address some known issues with the design and delivery of their current set of user assistance. Rachel worked with the Caplin team to design content that supports both of these goals; the result was Caplin’s new Developer website: www.caplin.com/developer
This case study describes the process we went through to design the new set of content, and how the new set of user assistance works as product marketing.
You will learn:
- How Caplin redesigned their user assistance
- How user assistance can support marketing and sales processes
- How to design user assistance that supports your customers’ purchasing journey
- What else changes when user assistance is used as product mark
Content delivered? Check. OK, how do we use it?
You spend months developing your content. You deliver it and sit back waiting for your users to say how good it is. The trouble is how many of your users really know how to get the best from it. You may be surprised how little they know.
For example, do they:
- Realise what content is there?
- Know how best to find what they require?
- Know how to navigate around the content?
In this presentation you will see how training your users about your content increases customer satisfaction and reduces support costs. If you can't do this directly, it will show how to get others to do it on your behalf. Whichever method is used this is also a great way to get direct feedback on your content.
Semi-automatic localization of screenshots
Localizing screenshots by retaking them in the localized software is time consuming and sometimes impossible. For instance, it could require configuration at the code level (SQL, HL7 etc) or the technical writer may have modified the screenshot since taking it. In such cases, one usually resorts to a graphics editor to fake the localized screenshots. However, this can be even more time consuming.
Picis has developed a way to semi-automate the process of localizing screenshots. The process requires MadCap Capture and Microsoft Excel. (Additionally, an image editor like Photoshop or PaintShop makes things easier, but is not essential.) In this presentation, Adrian explains and demonstrates this process.
Agile documentation: delivering in 2-week cycles
Working in Agile environment is one of the greatest challenges for technical writers nowadays. And what could be a more Agile environment than the Cloud? In this session, Dobrinka tells you about the challenges they met working for SAP HANA Cloud, and their strategy for success.
Every two weeks they deliver product updates reaching customers immediately. That is 24 regular documentation releases each year, not counting bug fixes and exceptional product updates. All content, reviews, quality checks, building and publishing needs to be finalized within the 2 week cycle. So, how do they do it? Dobrinka says working for the Cloud is like nothing she has ever done before.
In this case study presentation, Dobrinka describes her experiences of this project and explains how they were able to achieve the two-week cycles.
You will learn:
- Why would you want to deliver in 2-week cycles
- What are the challenges for delivering in very short development cycles
- What is their strategy for thriving in this hectic Agile mode (hint: DITA and constant innovation are involved)
HTML5: not just for geeks any more
HTML5 introductions, tutorials, and primers abound. These days you can't move a mouse without hitting a list of "must-use!" HTML5/CSS3 features. The problem is, many of the cool new features of HTML5—and their write-ups—are highly technical, intended for audio engineers, video producers, graphics artists, game designers, and other basement-dwellers. Doesn't HTML5 have features for regular writers? Yes it does, and we have 'em! In this session, we'll explore a selected set of semantic HTML5 tags and related CSS3 features that are actually relevant to real-world technical writers, examine some practical applications for them, and see them in action.
You will learn:
- How semantic tags differ from standard tags
- About the HTML5 elements that apply to technical writers
- How and where to use them in web pages
- How to use sets of tags for consistent results
Sessions in DITA track
Dynamic DITA delivery for Help
Virtual infrastructures, the cloud, and web apps — these change the way applications are deployed and used. Instead of separate applications on the desktop, or isolated servers driving centralized web applications, server infrastructure can now shift in response to changing need. This give us distributed, dynamic application environments. To support these environments, user assistance must be distributed and dynamic in kind. This presentation shows on-line Help that dynamically reads raw DITA topics and converts them to HTML. This is one way to address the challenge, and it provides unique opportunities as well. If you bring a web server installed on your laptop (WAMP or MAMP plus Perl), we can meet after hours to run this on your machine.
You will learn:
- What dynamic Help is
- How virtual infrastructure and web applications drive the need
- Immediate advantages of DITA for small-scale, Agile projects
- One Help delivery architecture that can put intelligence in each distributed documentation node
- New UA opportunities this approach can offer
Adding custom functions to your DITA project
The DITA build process, while robust, is not specifically geared to individual output formats; that's the beauty of single-sourcing. But HTML output types are more flexible and extensible than others, and it would be great if we could add HTML-specific features in a DITA project. Well now we can! This session shows you how to modify the DITA build to recognize slightly-modified standard elements and process them into author-specific functions. We'll cover using DITA element IDs and classes to achieve attractive and useful HTML features like pop-up definitions, expander links, and dropdown paragraphs. Caution: XML, XSLT, HTML, CSS, and JavaScript ahead — but nothing you can't handle!
You will learn:
- How the basic DITA build process works
- How to customize standard DITA elements to trigger specific behaviour
- How to modify the build process to recognise your customised elements
- How to include and execute the functions in the HTML output
Using indirect linking for componentised Help
Compared to ordinary hyperlinks, indirect linking provides a more powerful and flexible way of connecting topics within componentised or modular user assistance. From ALinks (introduced by Microsoft into Windows Help almost 20 years ago) to the keydef/keyref mechanism in DITA 1.2, indirect linking is supported by a wide range of user assistance tools and technologies.
This session describes the key principles and concepts of indirect linking, and explains the benefits that it has provided to SAP. SAP’s Technology and Innovation Platform unit has been working with Ixiasoft to implement a cutting-edge solution for the challenge of increasingly complex documentation and shorter shipment cycles. It leverages the full benefits of the DITA 1.2 keydef/keyref mechanism by using them for virtually every link in our documentation. Relying on the flexibility of indirect linking and the use of logical IDs, this implementation of the Ixiasoft DITA CMS provides SAP with solid versioning without having to branch all content with each new release, as well as managed reuse across multiple structures and versions. The result is a scalable model that works for simple products, but also provides the flexibility to model more complex products and releases.
DITA Questions and Answers (Q&A)
Panelists include:
Priscilla Buckley
Chris Despopoulos
Dave Gash
Moderated by Dr Tony SelfThis is a unique opportunity for you to put your questions about DITA to a panel of experts, including Dr Tony Self who is a member of the OASIS DITA Technical Committee and chair of the DITA Help Subcommittee. Come prepared with a list of questions, problems, and issues with which to challenge the panel.
You will learn:
- Everything you always wanted to know about DITA!
