Monthly Archives: April 2012

techpubs wiki writing

Must Read: Confluence, Tech Comm, Chocolate

“Who cares about printing money, let’s print chocolate!”

–Chapter 23, Driving Wiki Development, Confluence, Tech Comm, Chocolate

Do you need proof that Sarah Maddox, author of Confluence, Tech Comm, Chocolate: A wiki as platform extraordinaire for technical communication, is a complete chocolate and wiki expert? Let me tell you, she knew that one day we will print chocolate in our (industrial-grade) kitchens. And sure enough, that day has arrived! And so has her book. It’s a wonderful addition to the XML Press family.

Sarah has an amazing knack to start at the beginning and introduce wikis in a friendly way even though she has been living the wiki life for years. She writes an introduction to wikis in an approachable way and ensures the reader knows the context is technical communication. But for me there are technical details revealed that offer the best chapters of this book. There is the deep technical dive into “building online help” especially her case study of web-based, context-sensitive online help. This solution should rock your world if you’re looking for a cross-platform web delivery of your online help. Her chapter about “a day in the life” of the wiki is just what you need to understand how this delivery and collaboration solution is different from “ordinary” technical writing. And I thoroughly reviewed and enjoyed “Giving your wiki wings.” Wikis with wings are the way technical writers will show their value to the world. I especially appreciate the chapter “Driving wiki development,” where Sarah is clearly honest about gaps in wiki functionality and how we can actually improve our experiences with wikis.

This book is an important, essential addition to the professional writer’s bookshelf. I’ve already whole-heartedly recommended it to an entire team of Rackspace writers and to all my Austin-based writer friends who have listened to me talk about the changes in the industry over the years. I want to recommend it to all of you as well. This book offers both visionary inspiration and the nitty-gritty technical details for all of us working in this web-centric world. I have so much respect for Sarah’s work on this book. Her enthusiasm for the wiki way shines through each page – web page and printed page. Pick up a copy, devour it like a chocolate bar, and drive collaboration for technical content.

Buy now at Barnes and Noble

Buy now at

techpubs writing

Command line reference with true scrolling

I’m at the OpenStack Design Summit this week, and one of the OpenStack companies here, Piston Computing, created a pen that contains a scroll inside.

When you open the scroll, you can see all the commands available for the “nova” client, which is how you send commands to the OpenStack Compute API at the command line. Clever!



Musings on Collaborative Authoring

I’m reading new thinking from Adam Hyde, FLOSS Manuals founder, in a new book titled “A Webpage is a Book” at I found the gem of a quote above in the section on collaboration. He is re-writing his book about book sprints in this new tome. I knew he had been refining his thinking after running 30 book sprints over the last five years, so I look forward to hearing his new perspectives as he shifts from “it’s editorial” to “it’s ease of production, collaboration, and reuse.”

The best motivation to collaborate on writing a book is a desire for the book to exist. To quote Antoine de Saint-Exupery:

“If you want to build a ship, don’t drum up people together to collect wood and don’t assign them tasks and work, but rather teach them to long for the endless immensity of the sea.”

My current thinking about how to get collaborative writers to long for the endless immensity of the sea, the journey from uncoupled thoughts and notes to a knowledge transfer device, is threefold:

  1. Make your writing events fun and relaxing, like a writer’s retreat. The tool should disappear into the background while you just write productively. They desire for the book to be a part of their lives.
  2. Give the writing group plenty of reputation building – teach them to long for the recognition that being an author on the deliverable will bring. They desire for their writing to be recognized.
  3. Recruit people who already practice reciprocity – they get a kick out of being helpful. They know others helped them. They want to help and have been helped. They desire for their writing to be helpful.

Of course it’s not really this simple, but it is calming and inspiring to think of riding ocean waves to explore collaborative authoring. Holding a seashell to my ear now… ahh.