ArtsAutosBooksBusinessEducationEntertainmentFamilyFashionFoodGamesGenderHealthHolidaysHomeHubPagesPersonal FinancePetsPoliticsReligionSportsTechnologyTravel

The IBM Technical Writing Trilogy

Updated on February 10, 2018
Source

IBM has been a leader in many fields of office and computer technology since it was founded more than 100 years ago. Its recent leadership activities have included cognitive computing, in which human-like perception and reasoning is programmed into computers.

To make IBM products more usable, high quality technical instructions must be written. So it's no surprise that IBM has emerged as a leader in technical documentation, with the recent publication of three books that cover different areas of IBM's technical writing process.

The contents of these books started out as internal IBM work processes, but they can be valuable tools for any technical writing team.

The IBM trilogy of technical writing books includes:

  • A general outline for technical writing (Developing Quality Technical Information)
  • A style guide to help make the writing and formatting of material clear and consistent (IBM Style Guide)
  • Guidelines for using the DITA (Darwin Information Typing Architecture) authoring process, which has been adopted by IBM and many other companies (DITA Best Practices)

Developing Quality Technical Documentation: A Handbook for Writers and Editors (Third Edition) (2014)

By Michelle Carey, Moira McFadden Lanyi, Deirdre Longo, Eric Radzinski, Shannon Rouiller, and Elizabeth Wilde

This book gives the reader an organized approach to writing high quality documentation, with the focus on computer software applications. The book succeeds at that goal by breaking down a writer's work into three basic priorities:

  • How easy is the documentation to use? Users are trying to get a task done. The less time that they have to spend with documentation, the more quickly they can finish that task. The technical instructions must focusing on the user's goals and give them accurate and complete information.
  • How easy is the documentation to understand? This priority applies good writing standards to the content decisions of the first priority. The IBM Style Guide helps with this priority.
  • How easy is the documentation to find? Documentation has no value if the user can't get to it, so the writer must make information as easy as possible to find within a book, help system, computer interface, or topic.

To support these priorities, the book includes detailed checklists that can be used as writing evaluation tools by writers, editors, and non-writer reviewers from development, quality assurance, and other areas. Also helpful are a detailed glossary and a section on resources and references.

As I read this book, I did have two concerns.

The book recommends that writers put as much information as possible in the user interface through field labels, pop-up help, and other methods. The authors often use the relatively new phrases "embedded assistance" and "progressive disclosure."

However, many writers might not be able to create user interface help, because of time, technical, or skill limitations. Also, many users might prefer offline documentation, so that they can read documentation before they start a software application or print out a task before they perform that task.

Another concern is the length of the book, which has more than 500 pages.

From my technical writing experience, writing teams can get caught up in long debates about the correct way to do something. These debates can easily lose sight of a writing group's main goal on a product development team—make a product easier to use, which in turn helps with customer satisfaction, which in turn helps with customer retention.

The thorough detail of this book could have the ironic effect of fueling such debates. Readers should combine the lessons of this book with usability testing and other research to get their work done both usefully and efficiently.

The IBM Style Guide: Conventions for Writers and Editors (2012)

By Francis DeRespinis, Peter Hayward, Jana Jenkins, Amy Laird, Leslie McDonald, and Eric Radzinski

This book helps with two challenges of technical writing that can create tension and waste time within a writing group:

  • Deciding how to write or format something
  • Justifying those decisions to editors, supervisors and other writers

This book is a valuable reference tool with many lists and tables that can help minimize these challenges. But it's also worth a complete read-through because of how it builds on the reader's existing knowledge of the English language to teach them how to be good technical writers.

The first few chapters re-enforce English class lessons in a technical writing context. These chapters cover language, grammar, and punctuation. Next are chapters that apply these basic writing rules to the bigger details of technical writing, like formatting, organization, and structure. From there, the topics get more specific, covering references, numbers, measurements, and computer interfaces.

Much of the reference value of the book is in appendices on marketing content, highlighting, and word usage. My personal copy of the book has bookmarks for capitalization, highlighting, commands, user interface guidelines, and word usage.

I should note that the book is most valuable for writers who are working with the DITA (Darwin Information Typing Architecture) method of authoring. This book complements the DITA Best Practices book that is part of the IBM technical writing library.

But this DITA-related material can still benefit non-DITA users with guidelines on:

  • Topic organization (task, concept, reference)
  • Highlighting, which DITA automates but which can always be done manually with non-DITA tools

DITA Best Practices: A Roadmap for Writing, Editing, and Architecting in DITA (2012)

By Laura Bellamy, Michelle Carey, and Jenifer Schlotfeldt

Many writing groups are now using authoring tools that use the DITA (Darwin Information Typing Architecture) method of authoring. The DITA standard uses XML (extensible markup language) to do the following:

  • Automate the formatting of documentation
  • Categorize documentation into three basic topic types (task, concept, reference), as well as specialties like troubleshooting topics
  • Automate links in electronic documentation

This book covers those basic parts of DITA authoring, along with other features that take advantage of the XML element tagging of DITA:

  • Metadata
  • Versioning
  • Reviewing
  • Commenting

If a writing group is getting started with DITA, this book covers DITA's usage of features that are familiar in other authoring tools like Microsoft Word and Adobe Framemaker:

  • Topic-based writing, including topic re-use
  • Conditional formatting

And if a writing group is considering or planning a move to DITA, this book has technical and management guidelines for converting existing documentation to DITA documentation.

© 2016 Bob Smith

Comments

    0 of 8192 characters used
    Post Comment

    No comments yet.

    working

    This website uses cookies

    As a user in the EEA, your approval is needed on a few things. To provide a better website experience, hubpages.com uses cookies (and other similar technologies) and may collect, process, and share personal data. Please choose which areas of our service you consent to our doing so.

    For more information on managing or withdrawing consents and how we handle data, visit our Privacy Policy at: https://hubpages.com/privacy-policy#gdpr

    Show Details
    Necessary
    HubPages Device IDThis is used to identify particular browsers or devices when the access the service, and is used for security reasons.
    LoginThis is necessary to sign in to the HubPages Service.
    Google RecaptchaThis is used to prevent bots and spam. (Privacy Policy)
    AkismetThis is used to detect comment spam. (Privacy Policy)
    HubPages Google AnalyticsThis is used to provide data on traffic to our website, all personally identifyable data is anonymized. (Privacy Policy)
    HubPages Traffic PixelThis is used to collect data on traffic to articles and other pages on our site. Unless you are signed in to a HubPages account, all personally identifiable information is anonymized.
    Amazon Web ServicesThis is a cloud services platform that we used to host our service. (Privacy Policy)
    CloudflareThis is a cloud CDN service that we use to efficiently deliver files required for our service to operate such as javascript, cascading style sheets, images, and videos. (Privacy Policy)
    Google Hosted LibrariesJavascript software libraries such as jQuery are loaded at endpoints on the googleapis.com or gstatic.com domains, for performance and efficiency reasons. (Privacy Policy)
    Features
    Google Custom SearchThis is feature allows you to search the site. (Privacy Policy)
    Google MapsSome articles have Google Maps embedded in them. (Privacy Policy)
    Google ChartsThis is used to display charts and graphs on articles and the author center. (Privacy Policy)
    Google AdSense Host APIThis service allows you to sign up for or associate a Google AdSense account with HubPages, so that you can earn money from ads on your articles. No data is shared unless you engage with this feature. (Privacy Policy)
    Google YouTubeSome articles have YouTube videos embedded in them. (Privacy Policy)
    VimeoSome articles have Vimeo videos embedded in them. (Privacy Policy)
    PaypalThis is used for a registered author who enrolls in the HubPages Earnings program and requests to be paid via PayPal. No data is shared with Paypal unless you engage with this feature. (Privacy Policy)
    Facebook LoginYou can use this to streamline signing up for, or signing in to your Hubpages account. No data is shared with Facebook unless you engage with this feature. (Privacy Policy)
    MavenThis supports the Maven widget and search functionality. (Privacy Policy)
    Marketing
    Google AdSenseThis is an ad network. (Privacy Policy)
    Google DoubleClickGoogle provides ad serving technology and runs an ad network. (Privacy Policy)
    Index ExchangeThis is an ad network. (Privacy Policy)
    SovrnThis is an ad network. (Privacy Policy)
    Facebook AdsThis is an ad network. (Privacy Policy)
    Amazon Unified Ad MarketplaceThis is an ad network. (Privacy Policy)
    AppNexusThis is an ad network. (Privacy Policy)
    OpenxThis is an ad network. (Privacy Policy)
    Rubicon ProjectThis is an ad network. (Privacy Policy)
    TripleLiftThis is an ad network. (Privacy Policy)
    Say MediaWe partner with Say Media to deliver ad campaigns on our sites. (Privacy Policy)
    Remarketing PixelsWe may use remarketing pixels from advertising networks such as Google AdWords, Bing Ads, and Facebook in order to advertise the HubPages Service to people that have visited our sites.
    Conversion Tracking PixelsWe may use conversion tracking pixels from advertising networks such as Google AdWords, Bing Ads, and Facebook in order to identify when an advertisement has successfully resulted in the desired action, such as signing up for the HubPages Service or publishing an article on the HubPages Service.
    Statistics
    Author Google AnalyticsThis is used to provide traffic data and reports to the authors of articles on the HubPages Service. (Privacy Policy)
    ComscoreComScore is a media measurement and analytics company providing marketing data and analytics to enterprises, media and advertising agencies, and publishers. Non-consent will result in ComScore only processing obfuscated personal data. (Privacy Policy)
    Amazon Tracking PixelSome articles display amazon products as part of the Amazon Affiliate program, this pixel provides traffic statistics for those products (Privacy Policy)