A Techie Tech Writer Blog

My article on Open Source User Assistance: Ensuring that Everybody Wins has been published by Open Source Business Resource, a peer-reviewed online journal focused on the business of open source software. The theme of the January issue is "success factors" for open source projects.

My thanks to everyone I interviewed for the article, especially Andy Oram for an extended conversation on the topic. Thanks to Dru Lavigne, editor of OSBR, for inviting me to submit to this issue.

I'd love feedback on the article, either here or on the OSBR site. The OSBR has additional "reading tools" available in a sidebar.

Ivan Walsh is a technical writer currently living in China, who blogs at I Heart Tech Docs. Several weeks ago, I was honored to be included in his list of Top 50 Technical Writers on the Web. He also asked me to do an email interview. That interview is now posted on his blog.

P.S. Thanks also to Scott and Aaron at DMN for including me in their list of Top Open Source technical writers on the Web.

Wired has a review of the Fitbit fitness and sleep tracker, which looks like a nifty device. More than just a pedometer, it can detect the intensity of your activity, and when worn while you are asleep, can detect the quality of your sleep from your body movements. The purchase price includes a lifetime membership in the Fitbit website for tracking all your data, including calories consumed.

However, it currently lacks a manual:

But in order to learn how to tell your Fitbit you are going to sleep, you have to hunt around on the website because there is no manual. The only instructions that come with the packaging are: To start using your Fitbit, go to fitbit.com/start. We assumed the dearth of information meant that Fitbit was so easy and self-explanatory, a manual wouldn't be needed. This is almost true, which is impressive and frustrating at the same time. We hear a manual is in the works, however.

On the Fitbit website, the "manual" is a single page with five bullet points. There is also an FAQ, which is a mix of questions about features, services, and how-tos.

There's just no excuse for this. Either do enough design and usability testing iterations to ensure that your product truly doesn't need a manual (good luck with that), or provide a manual. Hint: the number of products that are so intuitive to all users that no users need a manual is, to a first approximation, zero. Even iPods come with manuals. When I got my first iPod, I had to look in the manual to figure out how to change the volume — the famously "intuitive" interface was not obvious to me.

It's fine if the manual is all online, if the product's use is consistent with connecting to the internet. I'm just skeptical that five bullet points is all a user needs to understand the product.

As attracted as I am to Fitbit's combination of fitness and geekery, I won't be adding it to any wishlists until I hear about an actual manual.

thursday september 24 was national punctuation day

i observed this holiday by giving all punctuation marks and capital letters the day off

tomorrow im giving the lowercase letters a rest by using all capitals and lots of exclamation marks

This week I started a new job at a different company. As a result, you may see a shift in the topics I find to talk about on this blog. Probably less Python, more DITA. Of course, I'm still involved in FLOSS Manuals, Writing Open Source, and other things related to open source documentation. I will not be, and never have been, speaking officially on behalf of my employer. As ever, this is just me, talking about stuff I find interesting.

Here's a summary of Writing Open Source, Day Three: sprint day.

We spent all day at the Ginger Press, as the library is closed on Sunday. The food continued fabulous. Also, JAM provided Café-Tasse chocolates. (JAM is the first person I've ever met whose business card says "Evangelist, Senior Writer".)

I helped out with the Gnome team's user and task brainstorming, led by Lynda Chiotti. The Gnome doc team (all four of whom were at WOS), have committed to completely rewriting the Gnome User Guide with a task focus for Gnome 3.0, due for release next March. This will:

• Result in a much more usable document.


• Set a new standard for Gnome application docs to follow.


• Sidestep the copyright issues of converting the existing content to a Creative Commons license, as it will all be replaced.

The Drupal folks spent their time converting the Writing Open Source site from a conference focus to a community focus. There are now forums for Writing, Tech and Tools, Community, and "Ginger Press" (general discussion). We've also started sections for a sample style guide, and best practices.

The Drupal folks also had discussions about the possibilities of integrating Drupal with DITA, making it possible to use Drupal as a DITA content management system. They have other priorities in the short term, but are definitely bought into the value of DITA in the longer term. I'm very excited about this, because it helps to round out the open source tool set for DITA. The DITA Open Toolkit is a great thing for producing output from DITA, but there has been a lack of open source tools for authoring or managing DITA topics. Filling that gap would make DITA much more usable for the open source community, providing a framework for structured authoring for and using open source tools, and attracting more technical writers to work on open source projects to gain DITA skills.

Discussion continued late into the evening again, on a more serious tone this time, including issues such as reward systems for volunteers, and how to motivate those who are solid contributors, but will never be "rock stars". On the topic of attracting volunteers, Emma recommended reading The Experience Economy, which argues that selling "experiences" is the next stage for business. The relevance to open source is that people will pay (money or time) for experiences that they believe will transform them and give them skills they never had before. Too many open source projects advertise for volunteers based on what the project needs, not based on what the project can offer volunteers from the experience of volunteering.

The whole three-day meeting was very exciting and energizing. It was fun to share technical communication best practices with open source doc teams, and gratifying that they could see the value. I gained some good ideas for ways to encourage open source community members to contribute to documentation. While the group was small (about 15 attendees), it will form the core of what we hope will be a growing a community of open source documentation enthusiasts.

I'm in Owen Sound, Ontario, attending the Writing Open Source conference. Here's a recap of Day Two, the "unconference" portion of the meeting.

After another great breakfast at Ginger Press (sticky buns!), we headed back to the library by way of a craft fair and farmers market. Several folks bought jugs of Canadian maple syrup, while I got some bison jerky (less potential mess in the luggage).

Shaun McCance started things off by showing some of the tools that the Gnome documentation team is working on and with. Pulse is a status tracker that works by crawling information sources like source repos and mailing lists. Project Mallard is a documentation system that includes several pieces, but most significantly an XML schema, also known as Mallard, which is intended as a simpler, topic-oriented alternative to DocBook. ("Mallard" was supposed to be a code name, but stuck. The relationship of this name to DocBook is left as an exercise for the reader.) The question that immediately occurred to both Lynda Chiotti and me was, "Why not use DITA?" The answer seems to be that DITA did not have as much traction several years ago when Shaun started Mallard, and Mallard is now tailored to meet the specific needs of Gnome. Since he's focused on Gnome, he's not much interested in making Project Mallard a more general-purpose system. But since it's open source, it could be a starting point for developing much-needed front-end tools for DITA.

The discussion around Gnome led into a discussion of translation, and how to encourage translators to work on docs as well as UI. For example, 86% of Gnome 2.26 UI strings are translated into Arabic, but only 7% of docs. That led
into a discussion of raising the profile of documentation within open source projects generally. One idea that came out of today's discussions was to turn the conference website into a portal for discussion and resource-sharing for open source documentation across projects.

At this point, we broke for lunch, which included giant gingerbread man cookies for dessert. After lunch, I walked along the Syndenham River to Owen Sound Harbour, and took pictures of the grain elevators, at the behest of my brother, who sells grain elevator buckets.

After lunch, I presented about FLOSS Manuals and the book sprint approach. There was interest in using the FLOSS Manuals site for some doc projects, such as short, targeted guides for Gnome development. Folks were also interested in the planned re-implementation of FLOSS Manuals, which will be based on Django. Emma's post about it on identi.ca immediately turned up a remote volunteer interested in contributing to the effort.

I also did a little show-and-tell of pydocweb, just because I think it's so cool to be able to update API docs through a wiki.

Next, Dru Lavigne shared what she has learned about setting up a certification program for BSD. It's hugely complex, time-consuming, and expensive. Now I can see why STC has not seriously pursued this, despite the idea recurring perennially.

Before dinner, we had a field trip to Inglis Falls, just outside of town, at the urging of Mayor Ruth Lovell Stanners, who accompanied the group. Inglis Falls is where the Sydenham River cascades over the edge of the Niagara Escarpment, the same geological formation responsible for Niagara Falls. There was once a grist mill at the falls, of which only two millstones remain.

Back at the Ginger Press, dinner included free-range chicken with home-made relish, and carrot cake. The group hung out at the cafe late into the evening, long after the beer and wine ran out. Despite this, much hilarity ensued. I suppose we were giddy at being with other people who are passionate about both open source software and documentation. Not since I was in high school have I seen a group of people get so silly with so little in the way of pychoactive substances. It appears that mascot of the new website will be a woolly mammoth.

On the other hand, maybe there's something in the air or the water here. On my way back to my hotel, I saw a group of about four guys, probably in their twenties, skipping down the sidewalk to their car. They were not with WOS, but may have emerged from a karaoke bar. I guess Owen Sound just makes people happy.

I'm in Owen Sound, Ontario, attending the Writing Open Source conference. Today was Day One, with invited speakers. Here's a recap of the day.

A disadvantage of hotel wake-up calls is that they do not have a snooze button. If you start to snooze, they will not call you back in five minutes. As a consequence of this fact, I arrived late to breakfast, which was served at the lovely Ginger Press cafe, book shop and publishing house, run by Emma's mom. Mmm, pancakes and maple syrup!

After a chat with the mayor of Owen Sound, who dropped by the cafe to meet the conferees, we walked over to our meeting space at the public library, escorted by Charles the bagpiper, in Highland dress, updated by Keen sandals. I took pictures, but neglected to bring a card reader to get them off my camera.

Licensing for Authors

The first talk of the day was by Megan Langly Grainger, an intellectual property lawyer who prefers plain talk to legalese. She reviewed some basic concepts of copyrights, and gave an overview of some of the major licenses used for open source documentation.

• GFDL is intended for book-type works with few authors or revisions. It is not suited for massively collaborative works, because revision-tracking becomes very burdensome. It is also not compatible with GPL, CC-BY-SA, or CC-NC.


• Creative Commons is good for massively collaborative works, but is not suited for software.


• GPL is intended for software, not documentation (though FLOSS Manuals uses it for docs). Derivative works must use the same license, and must give access to the source.


• Dual-licensing is a way to deal with license incompatibilities. It can also be useful for market segregation. Be sure to think carefully about letting others use your work for their own commercial purposes.

One question that was asked was how to avoid infringing someone else's copyright on a procedure. There's only so many ways to succinctly say "Choose File > Open." Answer: Facts cannot be copyrighted. So, to the extent that content is factual, it is not copyright-able.

Megan also talked about publishing contracts, and especially non-compete clauses. Publishers often try to limit the other writing projects that authors can do while under contract. They don't want their authors undercutting them. However, they may not realize how related activities by authors can help promote their book sales. If you can, make sure the scope of the restriction is as small as possible, so that, for example, you can still do articles and presentations, and can write on related topics (such as new versions of the same software).

User-Centered Design for Modular Documentation

Lynda Chiotti, an information architect based in Owen Sound, talked about using user-centered design to produce modular, task-oriented documentation. These are best practices that professional tech writers generally know we should be doing, but don't always do. They are often lacking in open source doc projects, and unknown to non-professional volunteer writers.

Three factors for successful documentation:

1. user-focused


2. designed as modular, task-based


3. planned development

Other notes:

• Using personas helps you visualize users, tell their stories, and determine your goals for their user experience.


• Do your own user testing, because "user testing will happen" whether you do it or not. Bad software and bad documentation each set user expectations for the other.


• Do guerilla testing using whoever you can rope into being subjects, to keep costs low.


• Ask for factual feedback to screen out opinions and emotions. Use a mix of open and closed questions to manage feedback.


• Tell testers you're not the designer "even if you have to lie". Otherwise either people try to please you or they get cranky.


• If you have existing content, put it aside, and design the document structure first. You can add in existing content later, if it fits.


• The granularity for topics should be what the user needs in order to do one thing at one time.


• To help you define tasks, try IBM Task Modeler, which is Eclipse-based and can output to DITA.

Fame, Fortune, and Technical Writing

After a yummy lunch of salad, split pea soup, and butter tarts, catered by Ginger Press, Dru Lavigne spoke on Fame, Fortune, and Technical Writing (in other words, getting paid to write books on open source software). Dru has a nice little acrostic for her topics; I didn't write all of it down, but it spelled out "I WRITE". One of her major points was that would-be authors need to be involved in the community for the project they want to write books about. You will need help from the community, and that only works if you are part of the community, helping both the project and other individuals. To hone your craft as a writer, write daily; it helps you build a body of work, define your style, and find out what you like to write about.

Things publishers like to see:

• the size of your audience


• that your expertise is currently "hot"


• the scope of your work (i.e., you've been writing for a while)


• a well thought-out book proposal

Learning Styles and Documentation

Belinda Lopez is an instructional designer who has worked with learners ranging from preschoolers to astronauts (at NASA) and now manages learning programs for Canonical Software. Her lively talk on learning styles included passing out koosh balls and colored pipe cleaners for the kinesthetic learners in the room. There will likely be more discussion on Day Two of how to address different learning styles through audio and video.

Cat-Herding 101

Addi Berry shared her experiences thus far organizing volunteers as documentation lead for Drupal, "not a voice of authority, maybe a voice of shared pain". She noted that being a doc lead is not much about writing, but is very much about community organizing, dealing with the diversity of humanity that is drawn to open source projects. She sees her role as:

• Banging the drum about documentation to get attention from people in the larger project.


• Helping the group develop a consensus about direction.


• Communicating that direction, so the "cats" don't just mill around.


• Empowering people to do whatever it is that they're passionate about.


• Letting go and getting out of the way.


• Building trust and relationships.

The last point is key — people will only do what you say if they trust you.

Finally, my day ended with a delicious dinner back at Ginger Press, and a walk back to my hotel.

Here's an example of using the FLOSS Manuals' AJAX API to embed a remix of chapters from different manuals into this blog post. The embedded remix combines chapters from the How to Bypass Internet Censorship and Firefox manuals.

This is a work in progress that I'm tweaking. The API is beta.

Select an item in the left panel to read it in the right panel.

I'm leaving Sunday for the 2009 "Summit" of the Society for Technical Communication. I'll be co-presenting two sessions:

• Documentation with Blogs, Wikis, and Online Communities with Anne Gentle. In this session, Anne will talk generally about how Web 2.0 approaches can help technical communicators converse with end-users, and I'll highlight FLOSS Manuals book sprints as a specific example of bringing together online communities to create documentation.
• Understanding User-Generated Documentation: FLOSS Manuals with Scott Abel. I'll be helping Scott by giving a demo of the FLOSS Manuals site. In this session, FLOSS Manuals is cited as an example of user-generated content as a social and technological phenomenon: users not only can but do generate pretty good documentation.

Some events I'm planning or at least hoping to attend:

• Lone Writers SIG dinner on Sunday evening
• Usability and User Experience SIG breakfast on Monday
• Summit Tweetup Monday night
• Lone Writers SIG breakfast on Wednesday

Finally, I'm now on Twitter, so I'll be microblogging and monitoring the #stc09 stream. If you just can't get enough of hearing what's on my mind, my Twitter ID is jmswisher.