Monthly Archives: August 2008


XO BookSprint instructions

Adam Hyde of FLOSS Manuals wrote up these instructions for how to get involved with the BookSprint going on this week. I’m hoping to write blog entries that describe the planning sessions and surrounding practical advice for this type of writing sprint, but I wanted to let my readers know the basic overview of how to participate this very week. Thanks Adam Hyde! Adam’s presenting at DocTrain East this fall, if you’d like to know more about FLOSS Manuals and the remixing the system enables.

XO BookSprint

This week in Austin, Texas a team of writers are gathering together to immerse themselves in a one week intensive documentation jam.

The purpose of the Book Sprint is to produce documentation in 1 week to support the forthcoming 2008 roll-out off the OLPC G1G1. The team in Austin consists of members of FLOSS Manuals (Adam Hyde, Anne Gentle), OLPC (Adam Holt), Sugar (David Farning, Walter Bender), and the Austin XO Users Group, and YOU! We have set up the online tools so you too can contribute! To make a contribution please do the following :

1. Register
To contribute to the documentation you can register at FLOSS Manuals :

2. Contribute!
There are several manuals planned to be finished by the end of the week
(August 29) including a Sugar manual, an XO manual, and 5 Sugar
Activities manuals.  You can see the structure of the manuals here:
Sugar :

XO (OLPC Hardware) :

Sugar Activities :

To contribute you must register and then select a manual and a chapter
to work on. if it is not marked ‘complete’ then press the edit button!
Its as simple as that.

Contributions can include cleaning up layout, spell checking, adding
images, proof reading, or taking responsibility for writing one of more
chapters. You don’t have to be a technical writer or a super geek, you
just need to know how to write.

If you need to ask us questions about how to contribute then join the
chat room listed above and ask us! We look forward to your contribution!

For more information on using FLOSS Manuals you may also wish to read
our manual :

3. Chat
Its a good idea to talk with us so we can help co-ordinate all
contributions. We have a chat room for this using Internet Relay Chat
(IRC). If you know how to use IRC you can connect to the following :
server :
channel : #olpc-content

If you do not know how to use IRC then visit the following web based
chat software in your browser :

Information on how to use this web based chat software is here :

blogging techpubs wiki writing

How do people converse about technical topics today?

I have seen the eminent reinvention of technical documentation as we know it, which inspired me to begin chronicling my own observations and shifts in the field of communicating technical topics through conversation.

One such revealing moment happened while I was working on documentation for the One Laptop Per Child project on their wiki at The Give One Get One rollout  was hurtling towards the organization, and they had not completely designed a support system nor did they have a user manual ready to view online or to print. The Give One Get One program gave the opportunity for the first time for anyone in the U.S to buy a laptop and know that one additional laptop would be sent to another country. Through the nearly heroic efforts of one person building a new team self-named the Support Gang, an all-volunteer crew if I understood the situation correctly, a wiki-based Support FAQ came to life and a support email address was created and a support team made of volunteers was staffed.

The amazing revelation to me was that the wiki FAQ could and did answer so many questions because they came from real people, customers of the Give One Get One program. The questions were real questions from real users, so there wasn’t a delay in seeking out a subject matter expert. These were conversations happening on the wiki Edit tab or on the Discuss tab. See the History on for examples of the questions and answers that happened, and also notice the time stamps for some of the answers. The immediacy of the response is practically like an Instant Messaging conversation via the wiki FAQ page.

How did the community completely fill out these highly useful wiki pages? Or did just a few volunteers do it? It was the work of a few good people continuing conversations with real users or potential and upcoming customers of the little laptop. Community-supported email, forums, and IRC discussions rolled into these wiki pages. Supporting users was the work of college students, of parents who were anticipating their laptop’s arrival, and other non-professional writers. One such volunteer was Katie, a mom who is a mathematician by day, and an excellent FAQ writer by night. Her wiki pages and research around the wireless connectivity were extremely helpful to everyone who bought a Give 1 Get 1 laptop. Without her dedication, many of us couldn’t have connected to the Internet, and the user manual I continued to work on benefited greatly from her wiki contributions and knowledge sharing.

That the community created such helpful, useful, readable pages was a complete turnaround for my attitude about what sweat goes into writing and rewriting carefully crafted topics to then submit for review and sweat over again and again until a deadline comes. I thought, instead of toiling over the exact words and following a style guide, should I try to recruit and entice and motivate contributors from every professional or amateur background possible? Some paranoid types say that laymen and amateur writers could beat us at our own chosen profession. But “beat” is not the right term. It’s not a contest or an all-out competition, it’s a group effort towards a shared goal.

Armed with this revelation, I began studying how conversations and community attract the right combination of content and information to offer the right amount of technical communication delivered in the right manner. Part of my study involved hands-on creation of end-user documentation, including a PDF manual, using the  OLPC community’s wiki at, and also using a highly customized wiki engine at FLOSS Manuals,

Much of the labor and toil on those wiki pages and especially with the community volunteer atmosphere of OLPC and FLOSS Manuals is coming to fruition next week at the FLOSS Manuals BookSprint to document the XO laptop and the Sugar operating system for the students, parents, and teachers benefiting from the One Laptop Per Child project around the world.

How can we go towards documentation as conversation?

Tell me… and I will forget. Show me… and I will remember. Involve me… and I will understand.

Documentation as conversation means getting closer to the users and helping them perform well. Over the years experts such as JoAnn Hackos and Jared Spool have told us that this type of user-centered design and focus increases the quality of documentation.

H. Allen Brizee and Katy A. Schmaling wrote “Effective Workplace Writing” as a resource for the Purdue University Online Writing Lab (OWL), and they say “In the last twenty years, two important ideas have developed that help professionals compose effective workplace writing: rhetorical awareness, and user-centered design.” In my mind and from what I read, user-centered design is consistently related to Web 2.0 definitions. Where Web 1.0 merely served information blindly, Web 2.0 gives users a chance to interact with the information and each other using the web.

Taking off from the concept of user-center design, I’d like to talk about how to get even closer with real customers by starting conversations and enabling user assistance in interactions with users with a series of blog entries on documentation, conversation, and community.

Professional writers have more conversation-starting tools at their disposal than any other time in history. Techniques may include the use of blogs, wikis, forums, and social networking sites, but may also involve photos, simple stick figure illustrations, videos, virtual worlds, or instant messaging. What are your thoughts on a blog series to discuss modern methods for involving readers in the conversation surrounding technical documentation?

DITA techpubs work writing

Darwin Information Typing Architecture (DITA) reading list

Here’s a reading list for DITA materials when you’re just getting started. I’ve been fielding some questions via email and IM about DITA lately, and pulled this blog post out of my drafts. I hope it’s helpful.

Learning more about DITA

Getting started with DITA

Structured writing, structured documentation

BMC Case Study featured in The Rockley Report:

Is DITA Going to Tip? By JoAnn Hackos in the CIDM newsletter

Introduction to DITA book cover
Introduction to DITA: A User Guide to the Darwin Information Typing
book by Jennifer Linton and Kylene Bruski.

Planning for DITA Success: How to Set Up the Right Team and the Right
Strategy, Part I, by Steve Manning of The Rockley Group and Su-Laine
Yeo of Blast Radius

Planning for DITA Success: How to Deploy DITA, Step-By-Step, Part II,
by Steve Manning of The Rockley Group and Su-Laine Yeo and Paul
Prescod of XMetaL

10 DITA Lessons Learned From Tech Writers in the Trenches

Updated to add:
ISTC Communicator articles about DITA (2005-2007)

blogging writing

Fun with Wordle

I love this visualization toy, Woordle at, and as it turns out, I use the word “love” quite a bit. That and “really.” Who knew? :)

It’s quite fun to make a Wordle because of the animation you see while the word “cloud” is added to, so I highly recommend trying it for yourself. You can change the colors and fonts. Here’s the Wordle based on my blog:

I also enjoyed reading the backstory of Wordle’s creator – he works for IBM and created Wordle in his spare time with his employer’s approval. Neat!


A summer experiment with Google AdWords

This summer I had fun writing an article about writing AdWords ads – and seeing if I could use the AdWords network to sell my presentation audio and slide deck, A Technical Writer’s Role in Web 2.0: Wiki-fy Your Doc Set.

The article is availabe on site – Managing Small Content:Counting Characters. Here’s an excerpt:

As part of a summer experiment, I decided to find or create an information product that I could then sell using a Google AdWords campaign. Mind you, I have no prior sales or marketing experience, and I’m sure it shows! But in an age when one can experiment for less money than the cost of a few business lunches, I thought I’d see what I could set up. I’ll share my findings with you, and I’d love to hear your feedback on this approach.


Author-it and indexing

If you do a search on the Author-it Yahoo Group about indexing, you will find a wide array of knowledge about some of the best ways to set up indexes especially when you have multiple deliverables.

If you do a Google search for Author-it and indexing, you find out about the Author-it Xtend Indexing Service, but that’s not what this post is about. This post is about indexes on sub-books, the kind that give you page numbers, or links to HTML help files in an Index tab.

Indexing is as much art as craft as this Future of Indexing article states so well, and has a wonderful storied history in taxonomy, metadata (or metacrap as Cory Doctorow so eloquently pens), and the Dublin Core metadata model. Not exactly a simple endeavor, to provide keywords and synonyms and figure out which terms to use as sub-entries and duplicate as primary entries.

On the Yahoo Group, Sue Heim has suggestions about using index objects within index objects, nesting the indexes within one main index. Author-it is smart enough to merge multiple index entries no matter what the output. Here’s the general setup for an example set of two books, one for Windows, one for UNIX:

Main index object built with the two index objects listed below plus any index entries that are common to each book, and then also:

  • index object for Windows-based book containing entries just for that sub-book
  • index object for UNIX-based book containing entries just for that sub-book

Each book uses the main index object. This strategy sounds flat-out brilliant to me, and would certainly make for more manageable indexes (indices? But that sounds oh-so-formal and this is a blog for goodness sake.)

Author-it index object maintenance

One maintenance problem that I’ve run into and found a solution for is that sometimes index entries seem “hidden.” I’ll try to delete an index entry and Author-it tells me it’s in use somewhere, typically in this gigantic comprehensive index we’re using (because we haven’t yet implemented the cool sub-index idea). I’ll open the comprehensive index but can’t see the particular entry I want to delete because it’s a sub-entry to another entry, and it may not be named as logically as I’d like.

So, I export the comprehensive index to XML, and open the XML file in a text editor and search for the index entry object’s ID.

The Object ID is typically the second hit when you search for an Object ID because the beginning of the index has a listing of just Object IDs. You’ll be able to figure out what the primary entry is then, as this screenshot below shows.

Once you determine what the primary entry is, you can delete it in the comprehensive Index object, which then unhooks the dependency and you can delete the original Index entry object that you intended to delete. Whew! What are some of your tips and tricks for index maintenance in Author-it?


Scriptorium’s Framemaker wiki – knowledge sharing, brain dumping, and learning

Honestly, Sarah O’Keefe’s blog entry describing the new Scriptorium wiki at doesn’t do the content justice – there is really, really good stuff on that wiki!

I’d love to see this wiki become a hub and community for Framemaker users whether you’re just starting out or you’ve been maintaining Frame source for years.

Hightail it over there and register for a login.

Considering that we now have this Scriptorium wiki, the WebWorks wiki, the Technical Writing wikiversity, the DITA wiki at, and, technical writers have some nice wikis to join, contribute to, or just read. What other wiki communities are indispensable for technical writers?