Monthly Archives: September 2008


My DMN Communications Podcast Now Available

Scott Nesbitt and Aaron Davis have a great podcast show called Communications with DMN. I love these guys’ “brand of insanity” as Scott puts it.

We had a great time talking about wikis, FLOSS Manuals, and the recent One Laptop per Child BookSprint for about an hour. They had prepared at least two pages of questions and still had more to ask! It was great fun. Listen for yourself, please. Feel free to comment here or there, either place, I’d love to hear feedback on this interview.

Upcoming presentations in Austin and Houston

I’ll be presenting Documentation as Conversation at the Austin STC meeting Tuesday October 7th.

Austin When

Tuesday October 7th
6:00 – 6:30 PM: Networking
6:30 – 7:30 PM: Program
7:45 – 9:00 PM: Networking dinner

Austin Where

UT Commons Center – Room 1.138 [Map]

Then in November I’m going to make the trip to the Houston STC Meeting Tuesday November 11th.

Houston When
Tuesday November 11th
5:30 – 6:30 PM: Networking
6:30 – 7:30 PM Program
Houston Where
Holiday Inn Select
Here’s the description of my talk about ideas for social networking and documentation. I hope to see you at one or the other!

Documentation as Conversation: Working conversation and community into documentation using social technologies

Even if your documentation system does not converse with your users, your documentation can help customers talk to each other and make the connections that help them do their jobs well, play with technology at home, or learn something new in a classroom setting.

Instead of concentrating on single sourcing or the tools of the trade, this talk describes how you can think about documentation and user assistance in a conversational way, perhaps with the help of some social networking applications. I’ll also discuss the in-person FLOSS Manuals BookSprint as a use of a wiki paired with a community event to gather together writers to accomplish documentation goals for free, open source software projects.


FLOSS Manuals BookSprint captured in video

Talk about user-created content. I’ve become a video producer, amateur being the kindest description I can come up with for myself.

I haven’t been posting as much lately because I’ve been working on this video to describe FLOSS Manuals and the recent BookSprint. Take a look and let me know what you think.

Welcome sign
Welcome sign

Looking at the event in the rear view mirror with the camera off, I realize that I’m still blown away by the outcome of seven books being print-ready in a week of writing with about another week of clean-up. Edits are still coming in, which I think is great. The content is continually improving.

Adam Hyde also recently posted to the FLOSS Manuals discussion list that he has solved many of the widows and orphans problems he had with the pretty-print PDF versions. So we’re ready to start taking orders for books. Stay tuned for the best way to order your own copy, we’re working out the logistics.

Also, there’s a new Help Activity available for download that contains all our content from the Sprint. Now that is an exciting outcome – online help that goes right on the laptop.

Podcast production at

It went all too quickly, but for the past few months I’ve been working with Tom Parish on podcast production at I’ve since decided I can’t juggle quite that many balls in the air, but I’m pleased with how these podcasts turned out. I learned a lot about the behind-the-scenes work of recruiting interviewees, finding topics, and producing the shows. With an assertive goal of four shows a month, you have to be constantly looking for the next person to talk with, setting a schedule, and researching the topic well enough to come up with a set of 5-7 questions to fill a 15-30 minute recording.

Our goal with is to produce educational shows about Information Technology, ITIL (Information Technology Infrastructure Library), which is a set of standards published to help you tighten up your IT department and align it with the whole company, and Business Service Management which is a revolution for how IT departments can run in order to tie technology into business goals.

William Hurley – Seeing Transparency through Open Source and Enterprise Software

Mary Nugent – Preparing your Business Services for the Future

Dennis Drogseth – Value Proof for CMDB Deployments

Tom Bishop and Dan Turchin – The Mobile IT Worker – They Walk, Talk, and Keep Businesses Running

Mainframe Trends in Enterprise IT for 2008 with John Albee and Mike Moser

Peter Armstrong on Guiding Principles to Changing Behavior and Speeding the Adoption of BSM and ITIL

Doug Mueller – Taking the Service Desk to the Next Level

The links above go to the show notes for each show, which is basically a blog entry to entice people to listen to the show. My favorite is probably William Hurley with Mary Nugent a close second. And the Mobile IT Worker has some fun stories in it.

The neat thing about podcasting is that it lets people tell their stories. Stories are very difficult to convey any other way, although the Google Chrome comic does tell individuals stories in a unique way.

I’ve been on the interviewee side of podcasts a few times, and I’m planning another one this week with Scott Nesbitt and Aaron Davis of DMN Communications. But it was neat to be an assistant to podcast production even if only for a few months.

Reasons for moving towards a conversation, towards collaboration, towards the community

What if your user’s guide had to read like an Instant Messaging, or IM conversation – quick, real-time questions, fast answers, and tailored to nearly every potential customer situation? Harry Miller from Microsoft pondered this very question in a podcast in the mid-2000s.

Sometimes users expect precise answers from their user guide. When you work with a product, you want to be able to impress people with your knowledge and efficiency. Or, you have a particular aversion to truly learning a product that you have to use to do your job, but you only use the product once every other month to do a specific (perhaps boring) task. Your manual does not talk back to your users in either situation just yet. But the person who reads the entire manual cover to cover will have conversations in turn with the people to look to him as the expert in the office.

Even if your documentation system can’t “talk back” to your users, your documentation can help customers talk to each other and make the connections that help them do their jobs well, play at home with more fun, or learn something new in a classroom setting. I have ideas for how you can think about documentation and user assistance in a conversational way, perhaps with the help of some social media technology applications.

Now, there are plenty of good reasons for technical writers to avoid actual conversation with customers. We are not necessarily trained in diffusing an angry customer or in troubleshooting the product at the technical level that is necessary. But we are good at learning quickly and applying technology to solve problems. These are not skills left only to the young talkative type, the technically savvy geek, or the extreme extrovert.

You might think that the term social media or a buzzword comes up is that the technology is meant for young people only, or that you have to have a lot of spare time to appreciate things like social bookmarking or Second Life. But the reality is that communicators are already skilled with many of these technologies. We just have to be able to apply them to individual situations and build a business case if necessary.

OLPC techpubs tools wiki

BookSprint Laps

What is a continuation of a BookSprint called? I’m not sure what to call it, nor do I know which metaphors might fit, but there has been some additional energy emanating from the Austin-based OLPC BookSprint. In the week following the FLOSS Manuals BookSprint, OLPC has energized interns and staff members to continue refining existing chapters and adding new chapters also. As maintainer of the doc, I’ve been watching the changes on notifications and will make my own minor edits, but for the most part I’m just watching in delight at the outpouring of content. Another win for us writers is that the manuals will be remixed, output as HTML, and included on the XO laptop itself for deployments. My sincere hope is that good documentation will prove helpful to the support gang who work so hard on

I’m also completely tickled by the emails of encouragement and thanks coming from all parts of the community. Here are some excerpts from an email from David Farning, an awesome Sugar Labs community guy who I know I can learn a lot more from:

I realized this was not just a couple of programmers trying to throw
together a wiki as I watched Janet Swisher intensely studying the XO’s
battery.  Turns out she trying to determine if the installing the
battery section could be misread.  From my experience, a programmer
would have said, “If they can’t figure out how to put the battery in,
what’s the point of a fine manual.”

David Cramer, a tech writer at Motive, the company that hosted the
event, provided a excellent takeaway on tech writing.  ‘When I write, I
write for one person.  Usually, one person reads what I write. The rest
of the department just asks him….’  Very on point for SL (Sugar Labs) and OLPC.
With our limited resources, we can’t afford to target a broad audience.
But, can afford to target ‘that one guy’ who can spread our message.

Technical Communication bloggers have also caught on to the uniqueness and excitement of this community documentation site, FLOSS Manuals. Tom Johnson, Heidi Hanson, and Charles Jeter talk about it around the 7:30 mark of this podcast:

Quotes from the audio –
about the site “I’ve never seen anything quite like it…”
about the BookSprint “an amazing collaborative community type of event…”
about the FLOSS Manuals community “the social organization of it is going to give it it’s best foot forward…”

Adam Hyde has done an excellent round up of blog entries that talk about FLOSS Manuals. He took a picture of these covers of the books. They look so good and it’s so satisfying to see a book deliverable so quickly.

Additional excitement for this week centers around translation of the content. FLOSS Manuals has a side-by-side translation interface and all of the wiki interface is also in the language of the translators choice. See to see the Farsi FLOSS Manuals.


Where do you start conversations?

The biggest mistake is believing there is one right way to listen, to talk, to have a conversation – or a relationship. – Deborah Tannen

There are new social media tools being invented all the time, and traditional websites are also finding ways to incorporate tagging, sharing, and other collaboration helpers in their content.

I believe that a conversation doesn’t have to be a direct connection between technical writer and customer. I want to also think about how you help customers connect with each other.

So, let’s discuss ideas for starting conversations. You probably want to study the categories of contributions that you want to ensure match up with your role in your company.

Matching up your strengths and experience to the conversations helps to avoid stepping on toes or stumbling into conversations where you do not have the tools, background, or correct messaging to know how to deal with the situation correctly.

There are plenty of skill sets that are valuable in traditional user assistance deliverables that are easily transferable to a movement towards social network integration for user assistance. These skills include:

  • excellent communication
  • clear writing
  • good design
  • up front planning
  • keywords and indexing (tagging)
  • understanding of semantic markup

What other skills do you think writers bring to the conversation buffet that is the social web?


BookSprint – results!

What a week it was. I’m tired but very proud of what we accomplished.

We wrote seven manuals for One Laptop per Child in a week: one for Sugar, the operating system, one the XO, which is the hardware for all of the deployments for One Laptop per Child, and manuals for five Activities: Browse, Terminal, Write, Chat, and Record. I think our PDF page count is over 200 pages!

Cover pages from the seven manuals we completed.

Results – the XO Manual is available (56 pages) and the Sugar Manual is available (132 pages). While the XO manual still has some missing images (screenshots and such), and I’d like to keep expanding the “Beyond Activities” chapter in the Sugar manual, we met the goals of the Sprint. Documentation never feels “done,” does it? Updated to add: the images are in the networking chapter of the XO manual, yuh!

Here’s how the week went. Sunday afternoon, we met at my employers for about 2-3 hours to plan out the outlines for all the books and make sure the scope was appropriate for the writers we had. I had an online discussion the prior week on the OLPC Library list, where content is discussed, to get buy-in from the community on the scope of the books and the audience for the books. By focusing the audience, we helped set scope, and by asking questions about scope and getting feedback, we could further narrow down the outlines for the manuals.

Sunday night we had a nice social event with the XO Austin user’s group at Mozart’s coffee house and finished up the night at Hula Hut for a nice dinner and drinks discussion. This type of informal socializing helped us get to know each other.

In a great conference room at Motive on Monday, Tuesday, and Wednesday we wrote all day, as if it were a work day. Tuesday night we had a cookout at the hotel. We intended to have some more rest and relaxation Wednesday afternoon, but then decided to push it to the evening to keep the writing momentum going forward, but we all were tired enough to opt out of a 10 o’clock movie at the Alamo Draft House.

Thursday was spent as if we were in the last lap of the sprint, writing and finishing furiously, and Friday we spent doing cleanup in order to create all seven PDFs by the end of the day.

I’ll have a lot more to say about the BookSprint in the coming weeks and months, because I believe in this model for free documentation and I am so in awe of FLOSS Manual’s wiki toolset and remix capabilities. Updated to add: thanks to Adam Hyde, Aleksandar Erkalovic (aco), who was updating while we sprinted, and Lotte Meijer, who made the awesome covers for the manuals. Your group makes up an amazing team.

In the meantime, enjoy some of my favorite pictures from the event.

Adam quite happy with the resulting PDF printouts
Walter Bender of Sugar Labs, and Adam of FLOSS Manuals writing the day away
FLOSS Manuals' wiki interface even works in the Browse Activity on an XO laptop as shown in this screenshot!

What’s next? As the maintainer of the doc set in FLOSS Manuals, I’m monitoring notifications on every manual we worked on. I want to continue accepting documentation requests through the Comment system on each chapter of the manuals in FLOSS Manuals. I hope that the participants will continue to feel ownership and make updates as they see fit. We’re hoping to translate both the content and the FLOSS Manuals interface to Spanish to assist in and create efficiencies for Spanish translation of the content.

There are so many thank yous and acknowledgments for the hard work this week – I hope I have adequately personally thanked all who participated in the planning leading up to the sprint as well as the many people who participated in the sprint itself. I’m bursting with pride in the community effort here and hoping to keep the momentum going in an even, sustainable pace. For the next few weeks I need to get my energy back from such a “sprint” effort, but I’m very proud of our results.