Technical Book Edit: System Overview

My first project at IBM was editing the AS/400 Handbook and Builder–the “bible” for all things related to the AS/400 models and OS/400 server. IBM often re-invented its products by giving them new names. Eventually, the set evolved into the System i Handbook and Builder. These two books described every requirement, configuration, and option for each release of the platform.

When my mentor–a soon-to-be-retiring technical editor and dairy farmer named Lois–first introduced me to these books, she trained me on a program called IBM BookMaster. It was a green-screen application where writers coded and tagged their content using text markup language. At the time, the rest of the content that my department published had moved to Adobe FrameMaker but not these two behemoths. My first task was to migrate them to FrameMaker. Fortunately, I found an engineer on the other side of the IBM campus who could help me.

After the books were converted to FrameMaker, I had a lot of cleanup to do. Once I could see what these books looked like, I realized they had a lot of room for improvement. One of the last comments Lois made about these two books was, “Don’t bother editing them.” She didn’t explain why, but I could surely understand when I started digging into them and understanding their tight publishing schedules.

Both books were so large, I created divider pages for the handbook and tabbed pages for the builder to make it easier for our audience to find what they needed quickly in the printed version. I also wrote the abstract, preface, and cover bullets to describe the books more clearly. (They were often used in helping large enterprise customers make purchasing decisions.) Plus, the number of terms, names, and acronyms in the book, so I created long lists of them to run the search/find/replace tool on in order to establish consistency.

The editing schedule was so tight that I often had less than a week to review an entire book. The chapters were often reviewed in a round-robin style from the engineers to the marketing team, to the project leader, and finally to me–the editor. By the time the chapters came to me, I had little time but to check tagging, spelling, grammar, terminology consistency, and run a few automated tools. At one point, my manager said we could no longer publish the books as editions, but to keep them as live documents in a draft state. Even today, they exist on the web with the draft notice turned on.

As a professional editor, this news to reduce the overall book quality was difficult to take. But, the business determined that “good enough” was plenty to release the books to our customers. For editors in this position of being stuck between producing quality work and work that’s not ready for public use, we agree to disagree with business decisions that are beyond our control. I often made up for that lack of quality in these book in the other content I reviewed for the department.

The following PDF shows the System i5 Handbook as it was published in 2006.

The following PDF shows the System i5 Builder as it was published in 2006.