All writing projects have their own challenges and opportunities. When working with a co-author, there can be additional challenges to ensure that the manuscript is completed in a way that ultimately reflects a single published voice while covering all of the required topic areas.

In this article, Rex Hartson and Pardha Pyla, co-authors of the award-winning textbook, The UX Book 2 (Morgan Kauffman Publishing, 2019), share our experience of success working together at a distance. We have offered the following insight on how to manage issues of version control, file sharing, managing “pen” ownership, change tracking, handing off the pen, and organizing difficult text.

Version control

We have about 35 chapters in a technical textbook of 900+ pages. Each chapter is up to 30 pages in Word. We go over and over each chapter, editing and refining the content and the writing. By the time it’s ready for the publisher, we have 20 to 30 versions of any given chapter and we archive every version, just in case. (This is why it takes us a few years to produce a new edition of this book.) We use the files names to indicate the version number. For example, the file for the third version of the first chapter might be named “Ch01, Introduction.3.docx”. All files for a given chapter are in a chapter-level folder (e.g., “Ch01, Introduction”). Within that chapter folder, all old versions are usually kept in a sub-folder named “Old”.  The current version is the only one you see at the top level within the chapter folder, so we don’t edit an old version by accident.

File sharing

We do all our file sharing via Dropbox.  All versions of everything related to the book are in a large set of Dropbox folders and files, so we both can always see everything.

Managing pen ownership

The co-author who is currently editing a chapter is said to own the pen for that chapter and the other co-author may not do any editing to that chapter. We include the pen owner’s initials (RH or PP) in every chapter file name—for example, “Ch01, Introduction.3.PP.docx”. This establishes who has the pen for the current version and who did the editing of any older version.

We agree upon initial ownership for a chapter via email and we use email or telephone to handle any non-routine pen assignments.

Change tracking

Changes made during editing are usually done with the Word Track Change feature, allowing each co-author to see and evaluate each editing change made by the other co-author. That is a quality control process that helps identify changes that need further consideration or additional discussion.

Handing off the pen

To describe our pen ownership hand-off procedure, let’s say that co-author RH has just finished editing “Ch01, Introduction.3.RH.docx” and wants co-author PP to take the pen. RH will send email to PP, relinquishing the pen for Chapter 1.  Then PP typically will follow this procedure:

1. Create a new copy of this chapter’s Word file, incrementing the version number and switching to his initials as pen owner, creating a file named “Ch01, Introduction.4.PP.docx”.
2. Archive the old version (v. 3) in the “Old” sub-folder.
3. Open “Ch01, introduction.4.PP.docx”.
4. Process changes made and tracked by co-author RH.
   • Accept all agreed-upon changes.
   • Annotate small changes not accepted with the perceived issue and flag in the chapter for the originating co-author to see in the next iteration.
   • Note changes not accepted representing large issues for discussion via email and/or phone.
5. Save and print the file; punch it and put it in a notebook. Yes, we know, this is an old-fashioned step in the digital age. But we both strongly prefer to work on paper copies with pens in hand. Aesthetically, we both love the feel of a high-quality rollerball pen with smoothly flowing ink, and hand-writing is the epitome of embodied interaction that tightly couples the eye, brain, and hand into one creative activity with no thought about tools or technology. The extra step of writing and then typing is an opportunity to refine and improve the thinking and wording.
6. Read and mark changes needed in this round of editing. We use a red pen for changes. Anything we see in red is something that requires attention.
7. Type in the changes, thinking about each change again as you go. Cross off the red editing marks with a green china marker.  Green over red means a change has been taken care of.
8. Send email or make a phone call to the other co-author to resolve any remaining issues with this chapter.
9. Hand off the pen to the other co-author.

Design for writing

Writing is like any other creative activity—you need to start with design, which includes structure and content. Whether you are writing a technical textbook or a novel, all books have, or should have, a structure.  That is the backbone on which you weave your artistic prose. It’s about where you start, where you go with it, and how you get there.  Designing the structure is a top-down activity, looking at the overview.

Designing the content is typically a bottom–up activity, starting with details and then organizing them to fit the structure and to fit together. In a brainstorming technique we call ideation, you make notes about everything as it comes to mind, at any level and in any order. Then you organize all these ideas sequentially and hierarchically (for example, by affinity diagrams—see next section).

Organizing difficult text

Sometimes the text just flows beautifully while we are writing. We know what we want to say and how we want to say it. Other times we struggle with expressing our ideas and have to make multiple false starts.  This is when we resort to using one of our own tools for organizing data—an affinity diagram.  You start by writing down all the main points you want to cover, one point per Post-it note.  Spread them all out on a table. Move them around and arrange them in:

• A logical flow of the high-level points
• Hierarchical relationships of the details going under each of the main points

This simple process can be the key to good organization that you often cannot achieve with just linear thinking.

Good luck with your writing!  It’s a fun and rewarding adventure.

---

Rex Hartson and Pardha Pyla are co-authors on The UX Book: Agile UX Design for a Quality User Experience, 2nd ed. published by Morgan Kauffman Publishing. The book was awarded a 2020 Textbook Excellence Award from TAA.