Wednesday, March 10, 2010

Management Day - User Centred Development

User Centred Development (UCD) and Technical Communication - Stephen Chalastra


Despite the challenging weather, our STC Toronto Management Day was a huge success! Over 70 people attended the event, hosted by FrontRunner Training, in the beautiful and spacious main hall of the Estonian House in downtown Toronto.

As everyone enjoyed their delicious continental breakfast, STC Toronto Community President Anna Parker-Richards welcomed all our guests, and introduced the first speaker, Stephen Chalastra, who spoke about User Centred Development or UCD.

Stephen Chalastra is Manager of User Experience at Qualicom Innovations. He has over 30 years experience in the IT industry and a rich history in technical communication. This was his first time presenting this topic to technical communicators!

Defining UCD
Wikipedia defines UCD as: “A design philosophy and a process in which the needs, wants, and limitations of the end user of an interface or document are given extensive attention at each stage of the design process.” However, it's more accurate to call UCD user-centred development. To successfully
implement UCD, you need to be able to convince management of it advantages.

Many different phrases have described UCD throughout the years, including
  • GUI design
  • UI design
  • Interaction design
  • User-centred design (UCD)
  • User experience (UX)
However, the user experience is more than just usability. We need to remember that the user's goal is to perform a task, it is not to simply use your software. For example, users do not buy drills because they want the drill - they want the hole. That is, they want what the drill can give them, and not the drill itself.

Therefore, design by itself is not enough, and has to be more than just functional.
It must be easy to use, or you end up with something like a teapot with its handle and spout on the same sides. A case in point is Microsoft Word, which is often a struggle to use. By contrast, Madcap Flare was relatively well-designed.

UCD - Putting Lightning in a Bottle
UCD involves the challenges, goals and needs of both the business and users. It means designing a solution that will fulfill those goals efficiently and innovatively. You need to ensure the project is technically feasible, and validate the design with users at strategic intervals
. The UCD process, when done correctly, is like putting lighting in a bottle. It is the "magic" that results in products and documentation that are easy to use and navigate.

Unfortunately, it's easier to say how not to do UCD than how to do it. In a non-UCD environment, a single Business Analyst will ask users their requirements, and then give these requirements to developers who then create the software and pass it on to QA to test. The problem with this traditional process is that there is little collaboration amongst the all the players and the end users. There needs to be more than just one person (the BA) in contact with the user. Instead, with UCD, there is communication across disciplines, and users are involved at all stages, not simply at the beginning.

UCD and Tech Comm
UCD is not just about code development. Technical communicators need to create added‐value documentation, and not just document the basic UI. Because users are often involved only at the start of the development process, by the end of the process, an intuition gap exists in the documentation. Technical communicators need to close that gap and create documentation that actually adds value to the user experience. We
can do this by focusing on users and asking who are they and how will they be using the documentation.

Unfortunately, the technical communicators are often brought in too late into the process, with management stating the infamous phrase: “we can't involve tech writer yet – the code isn't ready”. UCD encourages technical communicators to be brought in as early as possible, in order to identify potential problems.

As an example of this: to delete the excess styles formed in Word, the online help only explains what you already know. To find the solution, you have to go on the Internet.
Technical communicators are in a particularly good position to find usability and design problems.

UCD @ Qualicom
In Qualicom's UCD process, the BA works with the interaction designer employing usability principles
; both work in synergy together. Technical writers are a valuable resource because they help document meetings between these two people. An interaction designer produces design guidelines, wireframes, storyboard and UI specs. All of this information is then passed on to the developers.

The Qualicom UCD road map involves several stages including: requirements planning and elicitation, analysis, UI design guidelines and functional specifications, and usability testing.

Requirements Elicitation
This stage involves understanding
the business's challenges and goals, constraints and assumptions. The users’ challenges and goals, needs, and their capabilities are also all explored and defined. The BA works with a usability designer. They must understand what is most important to users. Less frequently used modules of the application must be easier to use than the more frequently used ones, where the user will quickly become an expert. Requirements for documentation at this stage include asking how do users get their information now, how would they like to get it, what do they know, and what do they need to know.

Requirement elicitation
tools and techniques include: focus groups, contextual interviews, requirement surveys, documentation reviews, task analysis, competitive analysis, and a glossary. For all these things, one can get value to or from the tech writer. The
tech writer can help “step in” for the designer long after they are gone. Note that this stage captures information; it does not dwell on the value of it. That is done in the next stage.

Requirements Analysis
In this stage, you validate, prioritize and document the requirements. Validation involves confirming the support for the business goals and project scope and evaluating the level of detail of user tasks. Prioritization involves determining resources and funding, and balancing the development effort against the perceived benefits. Documentation at this stage involves categorizing information into related functional areas, and ensure that the wording is positive and testable.

In this stage, you must avoid scope creep. Otherwise, it is like giving a user many complex remote controls, instead of the single simple unified one that they wanted. You need to document requirements using user personas. The technical communicator can design a requirements documentation template to help facilitate this.

analysis also includes using uses cases, usage scenarios, a business data model, visualization and requirements specifications. There must be sign off at all stages.
Missing, incorrect or misunderstood requirements are responsible for bulk of software project failures. People who are too technical write requirements that are too technical. Quality requirements documentation that is meaningfully written leads to better user comprehension, more effective reviews, and better quality requirements.

UI Design Guidelines
In this stage, you need to know the business context of the product, and the company's corporate standards. If you don't know your users, you can't design or write for them. It is like the moose flying a plane with controls designed by raccoons – the moose can't use his hooves! You need to define expanded user roles using user profiles. Accessibility needs and usability principles are therefore critical at this stage.

UI Functional Specification
In this stage, you assess the use cases and begin to develop a vision of the user's interactions. You need to determine
which requirements are most relevant, which users will be impacted, and if the requirements fit naturally into the design model. You begin to develop a navigation flow which asks: Where am I? What else can I do? How can I get there?

Later, you can start to design prototypes. Wireframe prototypes are a virtual mock-up of the UI, and act as a blueprint for construction that you can use and test. A dynamic wireframe gives a preview of the product's interface where you can enter data into fields, and can generate a Word document dynamically from the wireframe. Code prototypes are used to test proof of

Design Reviews
In this stage, you review the design for feasibility and develop prototypes. It is an essential element of UCD, and keeps the users involved and engaged. You need to ensure that the design is on track, that all the required functionality is included, and that the navigation is clear and intuitive.

In the actual development stage, you involve the key developers early. The designs are reviewed for feasibility, and developers work with interaction designers to develop prototypes. Technical communicators can create the message text for the application, such as on-screen text and error messages.

The better the interaction and the interface design, the less need there will be for documentation fixes and band-aids. Technical communicators need to focus on creating added‐value help. To do this, we need to be involved as early in the development process as possible before the code is written. Involvement in design activities will lead to better documentation. Both technical communicator and trainers can be involved in integrating help into the interface, ensuring consistency in the UI, creating understandable message text, producing better project documentation, and testing the implementation against design.

The end result is "magic" - intuitive, comprehensive and meaningful products and documentation that are easy and fun to use.

Management Day - The Agile Process

Presented by Mike Sahota

Michael Sahota is an Agile/Lean coach, consultant,and trainer and an advocate of the Agile development process. He has been adopting Agile and Lean practices for over 8 years and has been in leadership roles such as Vice President, Director, and Team Lead.

Agile describes a newer, more innovative way to develop products, especially software. The goal of the agile process is to make peoples lives more humane, and help companies succeed. Although agile applies mainly to software, it can be used anywhere, in almost any type of project where requirements can quickly change.

What Is Agile?

The agile process involves people closely collaborating to produce a high quality product. It's about working together as a team to deliver value. The goal of the agile process is to improve the information flow: the rate at which valuable information is passed from one group member to another. To improve this flow, people need to work closely together. Ideally, this involves actually working together in a large team room, rather than sitting in individual cubes, cut off from each other in their own "information silos". The goal of agile is to reduce the intuition gap and the need to read large complex specifications, which are often simply ignored.

Many studies have shown that the agile process leads to better productivity, better products and a much better work environment. Many companies and organizations are now embracing this process. In fact, the U.S. Defense Department, the largest procurer of software in the world, uses the agile process. Other major agile companies include Yahoo, Microsoft, Oracle and Google. It used in everything from cell phones to websites.

Main Principles

The main principles of the agile process are: individuals and interactions, working software, customer collaboration, responding to change and craftsmanship. All of this is in sharp contract to traditional development methods, which emphasize processes, tools, complex specifications, contract negotiations, and following a rigid plan.

Traditionally, detailed specification and functional reports describe the project. In the agile process, a more relaxed approach is taken. A specific requirement should be able to fit on one card. Whiteboards are used constantly to allow for the free-flowing of ideas. People generally feel freer to comment on sketches rather than on fixed diagrams and formal looking reports, which have an aura of "unchangeability" to them.

There are many types or "flavours" of agile, the most popular being "scrum". Unfortunately, many places have not practiced scrum agile, but a false version nicknamed "Scrum, but”. That is, companies say they are practicing scrum "but" with some exception to the process. "Scrum, but” is actually the most popular flavour of agile, but is not true agile because it does not follow one or more of the agile principles stated above.

Agile Project Cycle

In the agile project cycle, the development team writes stories; these can be considered as "light" use cases. The cost of each story is estimated, and the cards are arranged by

by price. In this process, the business value is decided by the business, and not by the engineers. As a result, the engineers lose much of the power they had, and are therefore resistant to it. The key point is that decisions are made not by any one person or group, but by the entire team.

Agile is very different from the traditional "waterfall" type development process, and it can take some getting used to. However, the end result is a product that is better designed, and easier to use. Individuals become empowered because they know they are true stakeholders in creating the product.

Management Day - Content Reuse

Content Reuse

Pamela Kostur is a partner at Parallax Communications and a recognized content management expert.

Why Reuse?

There are many reasons to reuse content in your documentaiton. It's efficient, it eliminates duplication and inconsistency, its frees you from having to create content that already exists, it allows you to spend more time creating unique content, and it can enable you to improve your content.

Reusing content also saves money because it reduces writing, review, and translation costs. It can also save money indirectly by reducing calls to support centres, and preventing legal problems. One medical company was succesfully sued because of inconsistencies between their printed guide and website.

Information Nightmares

There are many examples available of content not being reused, and the unfortunate results. These include inconsistenices in product descriptions, food recipes, and technical instructions. Inconsistency is to be avoided at all costs, because it makes the user have to work to understand the information by forcing them to "rewrite" it in their heads. Also, users may not interpret the information correctly, leading to chaos and confusion.

Implementing Reuse

To begin to implement a content reuse strategy, you compare potentially common content and determine the differences. You identify the common elements, then design the element so that it will fit with your information requirements. An information element (or module) can be any size from a step to a chapter. Note that the modules are ultimately based on the user's needs, not the writers!


Structure refers to how the various information products are assembled. You carefully document the structure, describing what components a module requires and any variations depending on how the information is delivered, for example printed vs. online. You can assign rules and conditions for what each module can contain. Consistency is the key in developing and managing proper structure.


Note that reuse does not equal "usable". Reusing unusable content simply makes it consistently unusable! You still need to put the content in your structure consistently and use detailed writing guidelines. Standards need to be commonly understood and shared by all the writers.

Summing up, writing for reuse doesn’t just happen; you have to plan for it. The effort and cost required may be large, but so is the payoff. Documentation is produced more quickly and consistently, and at a higher quality.

Management Day - A Content Reuse Strategy / SmartDocs

Content Reuse With SmartDocs

Bryan Lynn is the founder of ThirtySix Software in Indianapolis, makers of SmartDocs.

A content reuse strategy need to be well planned, otherwise it may not succeed. You need a need technology that effectively supports the strategy, as well as sufficient training and deployment time.

Picking a Tool

There are many content reuse tools to choose from, so you need to carefully analyze the current state of your documentation system. To narrow down the field of tools you need to ask what capabilities your reuse strategy needs. These can include conditional text, text chunking, variables, document types, change notification, and XML authoring. Of course, your budget is also a large factor. Some solutions have an low initial cost and can then grow organically, others have a high upfront cost right away.

Ease of Use and Deployment

The tool you choose must make reuse easy, ideally integrating directly into main authoring tool. The reuse function must always be accessible. There should be a single point of entry to access reusable content. The content should be intelligent and not force user to do manual. Also, the tool should not force you to change your DMS (document management system). You want to make it easy on your IT dept, so the tool should work with your existing file infrastructure.

Growing the Tool

The tool should support organic growth. The problem with large (big bang) implementations is that if they fail, you have wasted much time and resources. You need to pilot a reuse strategy and technology with a team to demonstrate ROI. Start with a small product that has a small documentation set. Apply what you've learned, get buy in from management and expand the tool only when you are ready.

The solution should also support legacy content. If it does not, you can either not use older content or convert it to the new format.

Summing up, implementing a successful content reuse strategy requires careful planning and analyses of your reuse needs. When you finally do select a tool, you need to carefully monitor its implementation, to verify that it has actually done what you had expected.

(After the presentation, Bryan gave a demonstration of SmartDocs, a content reuse tool for Microsoft Word. Jacques Fauteux from Front Runner provided the hands on training for participants to try the software.)