Francis DeRespinis - The IBM Style Guide: Conventions for Writers and Editors

Conventions for Writers and Editors

IBM Press
Pearson plc
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

For sales outside the U.S. please contact:

International Sales

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 writingHandbooks, manuals, etc. 2. English languageTechnical English
Handbooks, manuals, etc. 3. Electronic data processing documentation. I. DeRespinis, Francis,
1948- II. International Business Machines Corporation.
T11.I15 2011
808.0270973dc23
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

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 isnt much focus anymore on grammar.

Having a style guide in our back pockets as editors and reviewers means that we neednt 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 attorneys 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