December is the month! PCI Compliance, 5th Edition is ready for pre-order and will be shipping on the 22nd. James & I are so excited to hear what you think!

But of course, this project is several years in the making. Even before James & I sat down in early 2020 to hammer out where we wanted this to go, I’ve been involved in this book since the 2nd edition in 2009. Back in the old days, Microsoft Word was the tool we used to get things done. But we have such better options these days to collaborate on projects like this.

As we talked with several industry folks about the project and our progress, one of you asked me to document how we collaborated on the book and what tools we used.

PCI Compliance, 5th Ed.

The last big edition of the book published eight years ago in 2014. To say technology has advanced with collaboration, version tracking, cloud, and backups is an understatement. I finished my Doctorate that year and have a vivid memory of one of my friends, Dr. Heather Randall, telling me how she lost the digital copies of her dissertation as she was nearing the end of her program due to a computer failure.

At the time, I was writing my own dissertation solely in a word processor with multiple backups across many cloud platforms to try to keep my work safe. When you are the only author, this is still an acceptable way to work today. But the moment you bring anyone else into the fold, things become much more complicated.

After thinking about the best way to manage this, I settled on having us write the book in Markdown managed by a git repository. Markdown took the formatting stress out of the equation and allowed us to really focus on the writing. Not to mention, its a text-based file format that is universally readable, platform independent, and has an ecosystem of tools to parse it into a number of finished file formats. This allowed us to craft some silly sed scripts to do mass editing when we discovered repeated problems across the text. We also used regular expressions extensively to ensure we covered all the topics and requirements we intended.

Patched Tube, by Morten Liebach

A baseline knowledge of manipulating text files certainly made things easier—a skill I credit to my years of working with *NIX operating systems.

After quite a bit of trial and error, this is the process that James & I agreed upon and used for the duration of our writing. In our world, every chapter was in its own markdown file—mainly because my source material was made that way. But an added benefit there was merges became easier if we coordinated on chapters we worked on ahead of time and used branches and pull requests for the changes.

  • Use Pandoc to convert original Word versions to Markdown format:
    • pandoc PCI\ 4e\ Chapter\ 1_FINAL.docx -f docx -t markdown -s --wrap=none -o "PCI 5e Chapter 1.md"
  • Do massive cleanups with sed scripts to remove strange artifacts or unify treatments of certain types of things (like section headers or call-out boxes)
  • Initial commit to git repo (probably should have been step 2)
  • Decide to work on a chapter (or particular multi-chapter theme), create a branch dedicated to that chapter (or multi-chapter theme)
  • Write until you are complete with the task at hand (editing a chapter from another author, fixing a specific item in your area of expertise, general top-down rewrite/edit) and commit branch back to repo
  • Create a pull request with changes and check merge compatibility
  • Assign pull request to other author for review and comment:
    • If no comments, merge and delete branch
    • If comments, go resolve until everyone is satisfied and merge/delete the branch
  • Rinse and repeat until the book is done
  • Use Pandoc again to convert Markdown to Word as the publisher asked for it in that format (but it could also convert to any format Pandoc supports, so that makes this a very useful part of the process):
    • pandoc PCI\ 5e\ Chapter\ 1.md -f markdown -t docx -s --wrap=none -o "PCI 5e Chapter 1.docx"

That is it! This workflow really worked out for us and allowed us to keep track of all of our changes perfectly. Any future group writing project that includes a book component will probably follow this format for me. If you have questions or comments, find me on Mastodon and we can chat!

This post originally appeared on BrandenWilliams.com.

Possibly Related Posts: