For a good part of my career, I had the great fortune of technical book editing for the IBM International Technical Support Organization (ITSO). It was the United Nations of technical gurus–IBMers, customers, and business partners from around the world. These gurus–called residents— applied to participate in a two-week to six-week project–called a residency. The residencies took place at one of five publishing centers across the US–Poughkeepsie, NY; Raleigh, NC, Austin, TX; San Jose, CA; and Rochester, MN. The residents who were accepted into the program worked with a designated project leader who managed the residency. These project leaders came from IBM locations around the world for a one-to-two-year assignment in one of the publishing centers.
The residencies brought together subject matter experts and novices to document scenarios or solutions on a particular product. The documentation resulted in a technical book (called IBM Redbooks), a paper (called an IBM Redpaper), a tech note (a short web-based tutorial), or a combination of these types.
Resident support
As the person in charge of technical book editing for the Rochester Center, before the project started, I worked with the project leaders to schedule training, an initial (agile) review, and an editing plan. The training was a 90-minute class where the residents learned about our writing rules, process, and tools (Adobe FrameMaker and custom plug-ins). I also offered technical support to the teams during their residency.
When the residents arrived and the residency commenced, the teams met with the onsite engineers to develop, run, and test various configurations. As they did, they documented their steps. After they wrote around three pages, I reviewed them and provided feedback.
In these reviews, I looked at organization, clarity, use of images, formatting, and areas that needed more information. Also, if a draft had heavy English language issues, I told the project leader so they could be aware. (Drafts with language issues most always meant more work for the project leader and the editor.)
When a project ended and the residents returned home, the project leader prepared the book for the engineering team to do a final technical review. Then, they posted a PDF of the draft on the web for comment by interested readers. To save time before sending the book for review, the project leaders sometimes asked me to do a quick formatting cleanup on the book. For these quick cleanups, I had little time–no more than a day–to complete them. I checked to make sure all chapters and files generated correctly in the PDF. And, I fixed any other major glaring errors in the book, such as missing figures, bad page breaks, page numbering, or long paragraphs.
Technical book editing process
After the technical review, the project leader integrated all comments and changes. Then, they submitted their book or document into a single queue (first-in, first-out) for final edit. As a new book entered the queue, a queue manager assigned it round-robin style to one of the 10 book editors on our team. When possible, the queue manager assigned a book to the editor from the same center as the project leader for ease of collaboration.
For each book, the final edit combined a development edit, content edit, a graphics review, writing, and rewriting. I reviewed them for accuracy, clarity, completeness, concreteness, formatting, organization, visual effectiveness, style, branding, and potential legal issues. Thanks to our corporate style guide, we had a clear understanding of what we could accept or not accept. During the process, I communicated regularly with the project leaders about the status or issues that might affect the entire book.
When the comprehensive edit was complete, I returned the marked-up draft to the project leader. They had only one week to review the edits and respond to the comments. If necessary, we discussed any issues in the draft that required more attention or clarification. From there, I reviewed the comments, integrated the responses, and edited the changes. As much as I wanted to do another editing round, our process allowed only for a quick proofread for obvious errors or typos.
After I finished the final edit, I sent the document to the project leader for final review and approval. Then, I made any necessary changes and published it through our in-house system. The final document was available on the Redbooks website as a PDF, with a few hard copies available for ordering.
Publishing cycle
The average technical book editing cycle time was about two weeks for a 300-500 page book. Factoring in the project leader’s review time and final changes, the entire publishing cycle took three to four weeks. After a book was published, a soft-copy update could be issued if technical corrections needed to be made.
At the end of each book edit, despite feeling like I just ran a marathon, I always felt a great sense of accomplishment. Our process didn’t allow for our books to be 100 percent perfect, but I took pride in knowing I did the best I could to get as close to it as possible. For some books, no matter how much energy I invested in them, I had to accept 80 percent for quality. In the end, business demands won. They often forced teams to complete their project and publish the book as soon as it was technically complete.
The biggest reward from work was the people. The project leaders trusted to me to do my best work and be objective, and they respected me for my knowledge and skills I brought to their projects. We worked hard, endured high stress at times, and shared lots of laughs. Also, the residents taught me so much about language, culture, and a general respect for diversity. I’ve been fortunate to have lasting, lifetime friendships with many of the people I worked with.
Sample technical book
The following PDF sample is from a project I consulted on from start to finish. Hernando, the project leader, had a project update for an existing book of around 800 pages. He was concerned about adding more content and increasing the size of an already large book. A standard update wouldn’t serve our customers well, making it difficult for them to read and quickly find the information they needed.
Hernando asked me how we could reduce the size of the book and still create a positive customer experience by giving the customers focused documentation. I suggested a couple of options. The team could break the book into a two-part volume series. Or, it could write a completely new book that focused only on the update. The series option would have been a lot of extra work to reorganize, so he opted to develop a new book.
This finished book, which was written by nine authors, ended up being around 430 pages. The book was 100 percent complete in content. However, I estimate it was at about 85 percent for quality with just a one-pass, comprehensive edit.