The IBM Style Guide: Conventions for Writers and Editors

Francis DeRespinis

Peter Hayward

Jana Jenkins

Amy Laird

Leslie McDonald

Eric Radzinski

IBM Press

Upper Saddle River, NJ • Boston • Indianapolis • San Francisco

New York • Toronto • Montreal • London • Munich • Paris • Madrid

Cape Town • Sydney • Tokyo • Singapore • Mexico City

Ibmpressbooks.com

The authors and publisher have taken care in the preparation of this book, but make no expressed or implied warranty of any kind and assume no responsibility for errors or omissions. No liability is assumed for incidental or consequential damages in connection with or arising out of the use of the information or programs contained herein.

© Copyright 2012 by International Business Machines Corporation. All rights reserved.

Note to U.S. Government Users: Documentation related to restricted rights. Use, duplication, or disclosure is subject to restrictions set forth in GSA ADP Schedule Contract with IBM Corporation.

IBM Press Program Managers: Steve Stansel, Ellice Uffer

Cover design: IBM Corporation

Marketing Manager: Stephane Nakib
Executive Editor: Bernard Goodwin
Managing Editor: Kristy Hart
Designer: Alan Clements
Project Editor: Jovana San Nicolas-Shirley
Copy Editor: Keith Cline
Indexer: Cheryl Lenser
Compositor: Nonie Ratcliff
Proofreader: Seth Kerney
Manufacturing Buyer: Dan Uhrig

Published by Pearson plc

Publishing as IBM Press

IBM Press offers excellent discounts on this book when ordered in quantity for bulk purchases or special sales, which may include electronic versions and/or custom covers and content particular to your business, training goals, marketing focus, and branding interests. For more information, please contact:

     U.S. Corporate and Government Sales
     1-800-382-3419
     corpsales@pearsontechgroup.com

For sales outside the U.S. please contact:

     International Sales
     international@pearson.com

The following terms are trademarks or registered trademarks of International Business Machines Corporation in the United States, other countries, or both: AIX^®, AS/400e™, CICS^®, DB2^®, developerWorks^®, ESCON^®, IBM^®, IBM Press logo, IMS™, iSeries^®, Lotus^®, Maximo^®, MVS®, Notes^®, OS/390®, RACF^®, Rational^®, Redbooks^®, Symphony™, System i^®, System p^®, System z^®, Tivoli^®, VTAM^®, WebSphere^®, z/OS^®, zSeries^®.

Java and all Java-based trademarks and logos are trademarks or registered trademarks of Oracle and/or its affiliates.

Linux is a registered trademark of Linus Torvalds in the United States, other countries, or both.

Microsoft, Windows, and Windows NT are trademarks of Microsoft Corporation in the United States, other countries, or both.

UNIX is a registered trademark of The Open Group in the United States and other countries.

Other company, product, or service names may be trademarks or service marks of others.

Library of Congress Cataloging-in-Publication Data

The IBM style guide : conventions for writers and editors / Francis DeRespinis ... [et al.].
   p. cm.
  ISBN 978-0-13-210130-1 (pbk. : alk. paper)
  1. Technical writing—Handbooks, manuals, etc. 2. English language—Technical English—
  Handbooks, manuals, etc. 3. Electronic data processing documentation. I. DeRespinis, Francis,
  1948- II. International Business Machines Corporation.
   T11.I15 2011
   808'.0270973—dc23
                                   2011017836

All rights reserved. This publication is protected by copyright, and permission must be obtained from the publisher prior to any prohibited reproduction, storage in a retrieval system, or transmission in any form or by any means, electronic, mechanical, photocopying, recording, or likewise. For information regarding permissions, write to:

     Pearson Education, Inc.
     Rights and Contracts Department
     501 Boylston Street, Suite 900
     Boston, MA 02116
     Fax 617-671-3447

Text printed in the United States on recycled paper at R.R. Donnelley in Crawfordsville, Indiana.

First printing October 2011

ISBN-13: 978-0-13-210130-1

ISBN-10: 0-13-210130-0

Foreword

Why do we communicators become so attached to our style guides? We believe they are necessary to promote consistency, especially at a time when we hope to use topic-based content in numerous scenarios to improve our customers’ experience. If the topics we write are not consistently presented, they will not fit together easily. If they are consistently presented, they will seem to speak with the same voice even though they are written by many individuals.

However, a style guide appears to have a power and influence beyond a simple desire for consistency. It seems to represent what we value about the art of technical writing at a time when we continue to widen the scope of whomever we call a technical communicator.

On the bright side, a well-informed style guide that represents a set of writing rules helps inform our discussions with people in the wide-ranging enterprise community. We want to encourage contributions to a body of useful information from people who are typically not well versed in the standards of writing for publication. Likely, many of the rules and recommendations that we record in our style guides are unknown among a general, albeit college-educated audience. For example, if our enterprise audience members use commas, they do so by hunch rather than by punctuation rules.

The requirement that we work across the enterprise with content contributors means that we will work with people who vaguely remember punctuation and grammar (even spelling) from elementary school. We no longer call it grammar school, which I almost wrote in the previous sentence, for good reason. There isn’t much focus anymore on “grammar.”

Having a style guide in our back pockets as editors and reviewers means that we needn’t face arguments over writing style based on the strength of opinion. I recall some years ago being asked to work with a corporate attorney who was a very poor writer. The request came from the CEO for whom the attorney worked. When I entered the attorney’s office, the air bristled with tension around the coming battle. Luckily, when I pointed out that there were basic rules concerning punctuation and grammar and spoke about them in an objective manner, I won over the attorney. He welcomed advice that did not appear to him to be a matter of personal opinion.

A well-organized style guide can provide guidelines for new Darwin Information Typing Architecture (DITA) authors as they make the transition from desktop publishing to structured XML. A DITA style guide, something I recommend to all the teams I coach, includes information about the proper use of XML elements. For example, I urge writers to use titles for the sections they build in concept information types. Although DITA allows writers to begin a section with a paragraph and no title, a best practice is to include titles with every section. Section titles provide a way to divide a concept topic into well-structured parts.

Style guides that include authoring guidelines for the correct application of DITA elements help build consistency in authoring that facilitates the use of topics in multiple contexts.

On the dark side, style guides can become battlegrounds in organizations that use the rules as a club to block innovation and experimentation. It is critical that the writers, information architects, and editors responsible for maintaining a style guide be responsive to changing practices. When a style guide grows with the author and user communities, it remains a vital resource.

I find style guides to be invaluable and often quite fascinating. Making The IBM Style Guide available to the author community is long overdue. We need the kind of guidance and example that a world-class style guide like this one seeks to provide. We face the challenges of a global authoring community with many levels of experience and education in the field of information development. All of those in the community need the advice that a changing and growing style guide provides.

The wealth of standards and examples in The IBM Style Guide has been developed over two decades and represents the experience and good judgment of the IBM information-development community. The council responsible for The IBM Style Guide meets regularly to update the information and consider new proposals from information developers throughout IBM’s global organization.

I especially like the combination of correct and incorrect examples. It’s challenging to discover interesting new practices, especially those that clearly support DITA. It should make the lives of many editors now working in the DITA environment significantly easier. Authors will find first-rate advice on writing usable procedures or creating tables that make the readers’ life easier. Editors and authors will find fascinating tidbits in the comprehensive section on word usage. It is simply fun to read the examples of what is preferred and what “not to use.”

So, let’s celebrate style guides that help us resolve arguments and support our need to create readable, usable, and minimalist information. Let’s celebrate style guides that help us to recognize that there are some standards for grammar, punctuation, and spelling that we should not forget at a time when instant messages and tweets appear to be taking over the world. Let’s celebrate style guides when they continue to change with the times.

I congratulate the IBM team that has put together a genuinely helpful and thoughtful volume. I trust that the wider community of information developers will welcome this addition to our resources and profit from the advice.

JoAnn Hackos, PhD

President

Comtech Services, Inc

About this publication

For more than 20 years, the IBM Style and Word Usage Council has been an influential and integral part of the IBM community. Consisting of highly experienced editors from across IBM, this volunteer team is dedicated to supporting their colleagues in creating and producing the highest quality information possible for IBM clients around the world. The council is responsible for managing the IBM Style and Word Usage guidelines.

The IBM Style guidelines define the corporate style, demonstrate good writing practices, and ensure a consistent voice and tone for all external IBM information. The Word Usage guidelines provide advice on preferred spellings, potential ambiguities, and terms for writers to avoid so that information is clear and consistent. These guidelines do not attempt to teach basic grammar and writing principles. The council references Merriam-Webster’s Collegiate Dictionary and The Chicago Manual of Style as resources for more exhaustive guidance.

The council meets on a weekly basis to evaluate style and word usage suggestions from worldwide colleagues, watch industry directions and developments, and discuss findings from their respective teams.

Over the years, the names on the council have changed, but the passion and respect for the work has not. This book represents many years of work by many dedicated volunteers, and we are excited to share this work with a larger audience. Over the years, at conferences and other industry venues, requests have been made to access the IBM Style guidelines, but for various reasons, these requests could not be fulfilled until now. On behalf of the council, we are pleased to share this information and hope that it provides the basis for your company or personal writing guidelines and acts as an inspiration to create quality information for any audience.

Francis, Peter, Jana, Amy, Leslie, and Eric

Acknowledgments

We are grateful to our colleagues and to our families who supported us as we worked on this book. With a project this size, you need some understanding from your family as you work late nights and some patience from your colleagues as they wait for you to grab another cup of coffee on the mornings following those late nights.

We of course want to express our sincere appreciation to our colleagues on the IBM Style and Word Usage Council for their contributions. The council members provided tremendous support of our efforts to pull this book together and did not complain when we asked them to attend additional reconciliation meetings and answer numerous questions as we took over meeting agendas. In addition to the book authors, the current council roster includes the following people:

• Phil Appleby, chair for many years and current co-chair

• Ida Audeh

• Kathleen Callaway

• Simcha Gralla

• Kathy Hancock

• Dave Harlan

• Ann Harris

• Cathy Johnson

• Larry Morlan

• Jenifer Servais

• Aimee Tabor

We are very grateful to Neil Dewhurst of the Hursley iBuild team for setting up a DITA build for us. We are also very grateful to our fellow writer of this book, Peter Hayward, whose DITA skills and assistance made our production work that much easier for all of us.

We want to thank Steve Hughes for designing the graphics and working with Peter Hayward, who made the screen captures.

We want to thank Michelle Carey for her contribution to the messages topic, Carla Quinn for her contribution to the glossaries topic, and Ronnie Seagren for her contribution to the indexing topics.

We also want to thank and acknowledge all the talented editors who have been part of the council through the years, including Elizabeth Wilde, the founding chair, for their contributions and caretaking of the guidelines.

Finally, we want to thank those throughout the worldwide IBM community whose comments and suggestions over the years have helped keep the IBM Style and Word Usage guidelines in step with the ever-evolving discipline of technical writing.

About the authors

Francis DeRespinis

After receiving his Master of Arts in Teaching from Harvard University, Fran embarked on a career in public school education in the Hudson Valley of New York. Eight years later and after one final cold and much too snowy winter, he fled to sunny South Florida where he began his career with IBM as the first Entry Systems Division production control specialist for the IBM Personal Computer products. Fran moved on to become a developer and writer of in-store IBM PC training materials for retail sales, a software division liaison for compatibility testing and software application development, a software product planner, and finally, in 1984, he began his current work as a technical editor for software products in Research Triangle Park, North Carolina.

Fran edits Service Availability and Performance Management software documentation and is a co-chair of the IBM Style and Word Usage Council. He lives in Raleigh, North Carolina, with his wife, Tricia, their two dogs, and a house full of good books.

Peter Hayward

Having gained a PhD from the University of London, Peter’s early career was in academic research, observing the life of plants. That was followed by some years in the book trade, both retail and wholesale. He joined IBM 15 years ago on a European-funded project to create a system for searching large databases of images, using image content as well as image metadata. He moved into software development and then to information development, and now works as an editor in the IBM Hursley Laboratory in England. From writing research papers and helping to copy edit a scientific journal, to editing books and catalogs, and now writing and editing technical documentation, the business of stringing words together has always played a part in Peter’s career.

Peter lives with his wife, Sandra, near Winchester in Hampshire. His three sons have long since fled the familial abode. When not at work, he prefers to abandon the computer in favor of Victorian technology and the smell of hot steam oil; that is, playing with model steam trains in the back garden. He also finds time to be a Methodist local preacher and for walking in the local countryside and more distant mountains.

Jana Jenkins

Jana joined IBM in 1983 and is currently Manager, World Wide Information Development and Content Community. As a manager on the Corporate User Technologies team, Jana is responsible for leading IBM’s Information Development community, overseeing communication, delivery, and implementation of strategies, standards, and best practices. She also chairs the Total Information Experience Quality Governance Board, an enterprise-level board composed of content experts from across the business units, with the mission to improve and support client information quality. Jana has held several positions during her tenure with IBM, including instructor, technical writer, technical editor, and manager. She is recognized within the company as a Corporate Master Inventor. She is currently Chair of the Interface Technologies Invention Development Team. She promotes creative problem solving and innovation throughout the company and mentors new inventors as they consider the possibilities.

Jana has a BA in Advertising Design from the State College of New Jersey and an MBA from Pace University. She lives in Raleigh, North Carolina, with her husband, David, son, Tyler, and daughter, Lindsay.

Amy Laird

Amy joined IBM in 2003 and is a technical editor of user assistance for model-driven development software. She is the team lead for a group of editors and is an advocate of plain language and minimalism. Amy has a background in writing, marketing, and publishing. She has edited several books and she created the corporate style guide at another global company.

Amy has a BA in English Literature from the University of Toronto, an MA in Language and Professional Writing from the University of Waterloo, a post-graduate certificate in Book and Magazine Publishing from Centennial College, and is a Certified Proofreader with the Editors’ Association of Canada. She lives in her hometown, Ottawa, Ontario, with her partner, Pete.

Leslie McDonald

Leslie has worked in a wide range of roles and areas since joining IBM in 1983. She began her career by working on IBM internal business applications as a programmer, tester, and application support team lead. In the early 1990s, she moved into software product development in the IBM Canada Lab. She worked mostly on compilers, first as a test team lead and then as a development coordinator, before turning her attention to technical writing. Later, Leslie spent five years in IBM Global Services, mostly as a writer, particularly in the sales support area. In 2005, Leslie moved back to the IBM Canada Lab as a DB2 editor.

Leslie has a BA in Economics and Economic History from the University of Toronto and a Certificate in Technical and Professional Writing from York University. She lives in Toronto with her husband, Richard (a fellow IBM employee), and cats.

Eric Radzinski

Eric joined IBM in 1996 as a technical writer documenting heterogeneous data access technologies. After spending six years as a writer, team lead, part-time editor, and part-time QA engineer, Eric transitioned into a full-time editing assignment. For the past nine years, Eric has been the editor and information architect for the IBM DB2 and IMS Tools portfolio, which consists of well over 100 individual products developed on four continents by culturally diverse teams that include both IBMers and IBM business partners. He has been a member of the IBM Style and Word Usage Council since 2002.

Eric received a BA in English with a focus on technical writing from San Jose State University in 1993. He lives in San Jose, California, with his wife, Tina, and their three children: Jacob, Joshua, and Chloe.