Below are links to PDFs of selected article reprints from previous issues of the Best Practices newsletter and e-newsletter. To subscribe to the Best Practices newsletter click here. To subscribe to the e-newsletter click here.
Effective information development teams continually adopt processes to maintain a competitive advantage in today’s global marketplace. Many information development groups struggle to meet customer needs while grappling with shorter development cycles, reduced time to market, and tighter budgets.
To meet these challenges, our department of 40 employees, which includes information developers, tools experts, editors, and managers, developed an initiative program that ensures continuous improvement to processes, products, and skill sets for the department and individual contributors while increasing customer satisfaction.
Customer partnering is a technique used to design information products by creating a long-term relationship between representative customers and information developers. Through a series of guided interactions, customers and developers learn how their information products are used (or not used). They use this knowledge to design new and improved information products. Like other forms of participative design, customer partnering uses aspects of contextual inquiry and focus groups, but it provides much more detail about how the company can meet customers’ needs, and it involves the customer much more deeply in the design process. Note that participative design techniques similar to customer partnering have been used in software development but rarely in the design of information products.
Managers seem to be ever on a quest for the right metrics to determine organizational health. However, an overemphasis on one factor—such as the cost of producing a topic of content—frequently leads to treatment of a symptom in isolation. A balanced scorecard enables managers to examine elements of their organizations on a regular basis and helps flag problems before they impact the overall performance of the team. This article discusses how to create a balanced scorecard for your organization that incorporates four critical dimensions.
Baumol’s Disease: Is There a Cure?
Bill Hackos and Charles Dowdell
In October of 2004, Bill Hackos wrote an article for the Best Practicesnewsletter, titled “The Information Developers Dilemma.” He gave a presentation on the subject at the 2004 Best Practices Conference in the same month. The thesis of the article and the presentation was to demonstrate that principles brought forth in Clayton Christensen’s book The Innovator’s Dilemma on “disruptive innovation” apply to our own technical-writing discipline as well as with competition among high-tech companies. Bill showed how companies are beginning to use new technology, in this case the internet, to do programming, engineering, and documentation in third world countries that have either a natural English language or people educated in the English language. We refer to this innovation as offshoring. Offshoring is feared by American technical writers as a threat to their jobs. In fact, most of us know colleagues who have lost jobs that were transferred to India or elsewhere.
Following the conference last year, Charles Dowdell made the discovery of a 1967 paper by William J. Baumol called “Macroeconomics of Unbalanced Growth: The Anatomy of Urban Crisis,” in the American Economic Review, about the effects of automation on the US economy.
We’ve been astounded by the similarity of the processes described by Baumol and Christensen. It’s as if the Christensen book is an update of how the late 20th century technological revolution has added to the woes predicted by Baumol 30 years before.
Building a Collaborative Writing Strategy
Rebekka Andersen & Charlotte Robidoux
Doing business in a global marketplace demands virtual collaboration. Sharing topics in a content management system requires writers to collaborate virtually. What does collaboration mean in technical writing organizations? To answer this question, we surveyed models of collaboration, especially one developed by Morten Hansen in Collaboration: How Leaders Avoid the Traps, Create Unity, and Reap Big Results. In this article, we examine how Hansen’s methodology can support the process of building and implementing a collaborative writing strategy, one that supports successful single sourcing solutions. We explore the benefits of collaboration, why barriers occur, and how to overcome those barriers. We also provide useful tools and strategies to help teams reach their collaborative potential.
Katherine Brennan Murphy
Learn how Geoffrey Moore’s seminal and influential work, Crossing the Chasm, might be applied to information development. Understand the characteristics of Innovators, Early Adopters, Early Majority, and Late Majority customers through the Technology Adoption Life Cycle and how these characteristics should influence the type of content you develop.
Chris Nitchie, Oberon Technologies
Keys are one of the most useful reuse mechanisms in DITA 1.2. However, their application is limited by the 1.2 architecture, which uses a root map to define the context for all key reference resolutions so that they all resolve the same way. DITA 1.3 introduces the “keyscope” attribute to establish a key scope around mapref and topicref elements. This article explains key scope and provides several use cases with examples.
Content Management—What Are the Real Cost Savings?
In building a business case for the implementation of a content management solution, most managers create a set of predictions about process changes that will result in cost savings and increased productivity. In this article, I divide the most common predictions into four levels from reductions in desktop publishing and translation costs to improved content reuse across the enterprise.
Crossing the Chasm
Review by JoAnn Hackos
Geoffrey Moore’s 1991 study of high-tech marketing strategies, Crossing the Chasm, is an invaluable addition to a information-development manager’s library. His insights assist us in better understanding our information and training customers and in developing our own strategies for information transfer. Moore also us recognize the struggle our marketing colleagues are going through to position high-tech products effectively. The better we understand why they think the way they do and what they are trying to accomplish, the better we will be able to contribute to the success of the products we support and develop.
Data Merge and Automation with DITA
This case study details the process of integrating a DITA-architected Parts and Accessories Catalog with an external pricing XML database using XSLT data merge techniques. The data merge technique improved the publishing efficiency allowing for faster catalog updates and multiple deliverables from the same data source. In general, leveraging a data merge technique, companies can benefit from delivering a single-sourcing strategy to enable audience specific publishing through multiple deliverables (print and web) leveraging a single source of truth repository.
Developing a Playbook Strategy for Efficient Collaboration
Charlotte Robidoux, Matt Abe, & Tom Dill
Collaborative writing teams need a framework to delineate roles, responsibilities, and tasks to avoid the problems encountered when managing granular content. A playbook is a collection of scripted tasks that ensures each member of a team know exactly how to coordinate with others. This article explains the need for playbooks, their structure and key content, and the research behind their formation. It offers practical guidance for developing your own playbooks along with examples.
Review the eight stages of DITA maturity and adoption, based on observations of presentations at DITA North America and DITA Europe conferences. We have observed considerable progress in the way organizations are developing, managing, and delivering content. Much like the CIDM Information Process Maturity Model (IPMM), engagement with content management has moved from a preponderance of immature organizations exploring the possibilities to mature organizations finding new ways to capitalize on their earlier investments.
Traditionally, benchmarking has been defined as the process of comparing the performance of one company’s products with the products of its competitors. For example, benchmarking provides companies with a method for determining if semiconductors perform equally fast and accurately, if application software products include the same functions, or if one’s automatic camera focuses as quickly and accurately as the competition’s. Benchmarking also provides a method for studying internal processes to ensure that competing companies operate assembly lines as efficiently, produce the same output from the same machinery, or process paperwork as efficiently. Benchmarks are the baseline measurements, the numbers to beat.
FrameMaker 11 Review
Learn more about the features of Frame 11 and its ability to play well for DITA and topic-based authoring.
From Managing Inputs to Managing Outcomes
Detailed technical information has never been more in demand. Customers want to know more in order to make better decisions. But the information must be easy to find and easy to understand. Even though web sites contain a wealth of value, they frequently are managed as an afterthought. Most organizations do not invest enough in their information because they only measure inputs. They only measure the cost of producing the information. This article discusses the importance of measuring outcomes of web-based technical content to show the real value that information can create.
From Monolithicity to Flexibility, Using DITA Keyrefs
A few years ago, SAP expanded its offerings in five market categories: applications, analytics, mobile, database and technology, and the cloud. The impact on SAP’s NetWeaver platform was profound. Some 50,000 information objects had to be decoupled and then bundled in varying subsets within the larger platform, with asynchronous delivery cycles and, in some cases, shared components. This article discusses the strategy that SAP developed to transition from a monolithic delivery to one of small, reusable components using the DITA keyref mechanism.
Document conversions can range from a few dollars to several hundred dollars a page. The final cost will depend on what kind of source material you are converting, what your target format is, what type of document you are converting, whether your conversions requires a review by a content expert, whether you require graphic conversion or content reauthoring, whether automated conversion tools can be used, and what other costs might be associated.
How We Use Minimalism and a New Form of Task-Oriented Help, WalkHub, to Overcome Cognitive Load in Web Applications
Kristof van Tomme & Diana Lakatos
The principles for good documentation such as minimalism, structured content, and topic-based authoring still apply on the internet. In fact, some of the major trends in web applications, such as robust and complex applications, Agile development, and social communication, make the tried-and-true principles more relevant than ever. This article discusses how writers can use these principles to cope with products that are constantly changing.
IBM Component Content Management System for DITA
Tonya Holt, Mike Iantosca, Ellen Patterson, & Sophie McMonagle
The Corporate Information Development (ID) Tools product development team at IBM is developing an end-to-end lifecycle management system that IBM ID teams are using to author, manage, reuse, and deliver product documentation for the company’s vast product line. This strategic content management system is known internally as Information Development Content Management System (IDCMS) Blue. This system, the result of an ongoing multi-year development initiative, serves as the core of an ID authoring tools ecosystem to enable the reuse and sharing of technical documents between technical writers across the enterprise; it also automates many ID processes and integrates with development systems.
The illusive productivity metric is often a challenge for documentation managers because it’s difficult to create valid, reliable, meaningful measures of how efficient a writing process really is. HOW to measure productivity can be as much of a puzzle as WHAT to measure. Cost per topic can be an effective productivity measure for several reasons: It is scalable, easy to calculate, and takes into account both the volume of the output and the actual cost of that output. By plotting this cost per topic rate over time and applying a statistical trend line to the raw date, the documentation manager can see a valid and reliable picture of the change in productivity over time. Changes in the trend line over time can clearly show managers whether productivity is getting better, worse, or staying the same, which can help managers make more accurate decisions about what to change (or not change) in the department.
One of our next big challenges in tech comm is delivery. The volume of information is exceeding capacity on laptops, massive libraries must be continuously updated, and heavy-hardware companies are now insisting that information be available at point of use, integrating task-based information with user operation. In addition, our new emerging users want to locate and access information by methods of their own choosing and want information made available their way. These growing demands generate a new plateau of challenges for content developers and architects to meet users needs with technology that can deliver new information faster, but in different venues in personalized ways. This presentation invites an interactive discussion on these new challenges and how our industry can provide answers going forward.
Indexing Effectively in DITA
DITA is useful for helping writers create small units of organized information that can be used in multiple contexts. Of course, the readers’ problem then becomes locating the information they want in a quick, reasonable timeframe. Although DITA provides enough metadata to simplify searching or even to present information the reader needs based on a profile, there are some media that cannot make use of those facilities. To bridge that gap, you can use the tried and true index.
Influencing Change: Negotiating vs. Building a Vision
In this article I present ideas on how to find data, how to use that data to build both a compelling argument and a vision for your team, and then how to leverage that vision for support and funding. Key to this process is learning how we need to make adjustments to our traditional way of thinking, evolving from “negotiation” to “vision.” This article suggests three basic components of using an approach, a strategy, and specific tactics. As a technical publications manager for many years, I summarize these lessons learned about pain points of discovery and perseverance, and reading the true messages behind rejection. Embedded in that discovery is the realization of the absoluteness of data, of using effective rhetoric, and understanding how funding works in the corporate environment. I present five examples of where technical publications managers can find the data to go after the funding they need.
Innovative information architects are molding their designs to influence product success, from extending content collaboration across the enterprise, integrating end-users into the content development process, decreasing time to market, and creating environments in which information influences the viability of the product. In this discussion, I introduce several case studies in which information architects are pursuing innovations in information development and delivery that contribute to the profitability of their companies.
JoAnn Hackos updated the Information Process Maturity Model in 2006 as a chapter in Information Development: Managing your Documentation Projects, Portfolio, and People. This reprint of the chapter shows that two new categories were added to the IPMM in response to changes in the information-development environment. These categories are Collaboration and Change Management. The issues surrounding these categories are discussed in the reprint, in addition to clarifications of the existing model based on many new studies.
Inside the Tornado
Review by JoAnn Hackos
In Geoffrey Moore’s follow-up to Crossing the Chasm, he describes the challenge of understanding the positioning of products in the technology development life cycle. In Inside the Tornado, learn how to analyze the products you support with documentation and training. Consider how to shift your information-development strategy at each life cycle stage.
Minimalism Updated 2012
The Minimalism Agenda, originally developed by John Carroll at IBM, continues to be researched and updated. In this article, learn how the four minimalist principles continues to be relevant to current user needs.
Predicting Cost Savings—Backing Up Your Claim
Most technical publications organizations today have either implemented a content management system and topic-based authoring or are thinking about how to make a business case for senior management support. At the heart of the business case is the prediction that spending all that time and money on new structure, processes, and tools will result in significant cost savings. In this article, I discuss how to predict cost savings and how to back up your claims so that they exert positive influence on the decisions makers.
In working with information-development groups who want to move into content management and a structured writing environment, I often find that the potential for the role of information architect is not well understood. Some groups believe that an information architect is a technical expert responsible for the tools and technology used to author, maintain, and publish content. Others believe that an information architect need simply concentrate on formatting final deliverables such as print, HTML, and help. Still others want a programmer who can produce a DTD (Document Type Definition) or similar code that reflects the existing format of the organization’s book.
Structuring Your Documents for Maximum Reuse
A major topic among information development managers these days is single sourcing—writing information once and using it many times. Structured documents are critical for single sourcing. So, let’s explore
- what we mean by structuring documents
- why structuring is useful
- some of the concerns that writers have about structuring documents
The Net Promoter Score (NPS) is used to survey customer loyalty to a product and brand. By asking customers to rank their likelihood to recommend your product to colleagues and friends, you measure the degree to which your product meets their needs. Adding NPS questions about that effect of documentation, training, customer support, or other post-sales support on customer loyalty provides you with critical information about the enthusiasm about your information-oriented services.
People are beginning to realize it is a category mistake to call some kinds of systems a “CMS” (Content Management System), when what they really are referring to is a “CCM” (Component Content Management) system. Under certain circumstances, the difference is critically important. By making this category mistake and confusing a “CCM” system with a “CMS.” some organizations are failing to convince their management that they need a specialized system called a CCM. Their management or IT organizations think they already have one, when in fact they do not. Organizations that succeed in adopting a CCM system have argued persuasively to management (if not to their IT organization) that a CCM system is not a CMS. Just as a source control system (which does versioning) is not a CMS and just as a Web Content Management (WCM) system is a specialized type of content management system, so a CCM system is a unique specialized system for the management of another critical enterprise function: namely the management of technical information.
|Components of a Professional CMS Implementation |
2006 CMS Conference slides from JoAnn Hackos and Miel De Schepper
Content Management—Are You Ready for Content Management?
Content Management—The Magic Behind the Web
JoAnn Hackos discusses content-management systems in an article for webreference.com
Content Management: Your #1 Resource for all Types of Content Management Applications
A variety of articles and links to information on content management
Redesigning a Single-Source Content Management System
Developing a Content-Management Strategy: Implications in a Multi-Language Environment. A 2001 presentation by Compuware Europe’s Barbara Douma
Selecting a Content-Management System
2002 STC Conference slides from JoAnn Hackos
Selecting a Content-Management Solution
2002 STC Conference slides from JoAnn Hackos and Tina Hedlund
Darwin Information Typing Architecture (DITA)
An Introduction to the Darwin Information Typing Architecture
An article by Don Day, Dave Schell, and Michael Priestley (IBM).
DITA Deep Dive
A small collection of tutorial materials prepared for OASIS TC DITA Overview Sessions, held on May 25, 2004 through June 2004, via teleconference.
DITA is an architecture for creating topic-oriented, information-typed content that can be reused and single-sourced in a variety of ways.
DITA Technology Review
An article by Michael Priestley (IBM).
IBM Downloads on DITA
Several resources on DITA are available through the IBM web site.
Moving from Single Sourcing to Reuse with XML DITA
An article by Lori Fisher (IBM).
OASIS Open Standard on DITA
IBM donated DITA to the OASIS standards organization in March of 2004, where it is now managed by the OASIS DITA Technical Committee.
Total Information Experience: Defining an IBM-integrated Approach to Developing Information in a Flat World, via Effective Global Collaboration
Eileen Jones and Dave Peterson’s presentation from the September 2006 Best Practices Conference.
Information Development in a Flat World
33rd Annual Council on Programs in Technical and Scientific Communication Conference slides from JoAnn Hackos
Best Practices for the IT Consulting Industry
A resource by Meryl Natchez, CEO of TechProse
Delivering the Right Content, to the Right Person at the Right Time: Aligning Practitioners with the Strategy
Presentation slides from Lori Fisher, IBM Corporation
Demystifying Information Modeling
Presentation slides from JoAnn Hackos
Information Developer Job Description
A detailed job description for hiring an Information Developer
Localization Industry Standards Association (LISA) newsletter
A monthly e-newsletter by LISA
Making a Business Case for CIDM Membership
Trying to make a case for CIDM membership? Present this resource to your upper management if they have questions about the benefits CIDM Membership will give you
New Manager’s To-Do List
A presentation from Independent Consultant Marty Williamson
The Role of an Information Architect in the Technical Information-Development World
JoAnn Hackos discusses the role of an Information Architect in this 2005 article from the Best Practices Newsletter.
Seven Things New Managers Must Do in the First Ninety Days on the Job
Presentation slides from JoAnn Hackos and Marty Williamson
The Shackleton Way
A STC Conference 2004 presentation by Bill Hackos
Information Process Maturity Model—A 2004 Update
JoAnn Hackos writes an update to the Information Process Maturity Model
A Writer’s Guide to XML Content Management
Presentation slides by JoAnn Hackos and Tina Hedlund
Building a Common XML Architecture for Nokia—A DITA Case Study
A 2004 Content Management Strategies conference presentation by Nokia’s Indi Liepa
Translation with XML
A 2003 Best Practices Newsletter article by Bryan Schnabel of Tektronix