A Techie Tech Writer Blog

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.

Atlassian, the maker of the Confluence enterprise wiki and the JIRA issue tracker, are selling licenses of those two programs for up to 5 users for $5. Support is renewable for $5 per year. Forever.

Details are on the Atlassian website. Thanks to Sarah Maddox for publicizing this.

Sure, there are open source wikis and issue trackers you can get for free. You might even be able to get decent support for them. But this is almost free, and proceeds will be donated to Room to Read, which builds libraries and schools in the developing world.

The offer lasts through Friday, April 24th, or when Atlassian reaches its fundraising goal, whichever comes first.

I'm getting one of each, and I'll decide what to do with them later.

Every year, the Austin chapter of STC conducts a salary survey of tech writers in the Austin area. Since the international STC stopped conducting salary surveys a couple of years ago, the Austin chapter's survey is the best available source of salary and contract rate information for the Austin area.

However, the survey results are most valid when a large number of technical communicators participate in the survey. Response rates for the survey are down this year. It may be that a number of people have let their STC memberships lapse, due to their economic situation, and therefore haven't gotten the word about the survey. But you don't need to be an STC member in order to participate. The only requirements for participation are:

• You earn at least some of your compensation by being a technical communicator.


• Your primary residence was in the greater Austin area for at least part of 2008.

Salaried employees, contract employees, and independent contractors are all encouraged to respond. You can find a link to the survey on the STC Austin chapter website. The survey is open until April 20th, 2009, 11:59pm CDT.

Update May 17, 2009: The survey is now complete, and results are available on the STC Austin website.

Reflections on David Esrati's keynote at DocTrain West last week, The Content Providers Crystal Ball: What Everybody Missed During the Digital Revolution have been bouncing around in my head, though perhaps not in ways that he intended. This stuff is probably old hat to the pundits whose job it is to pontificate on "Web 2.0". That's not my job, so it's still interesting to me. This post is a somewhat rambling dump of those thoughts.

Esrati is in advertising, and his presentation oddly resembled the beer commercials he derided in his talk — it was highly entertaining, yet poorly targeted for the actual audience. Did an audience of technical communicators really need a history of mass media advertising since the dawn of radio? No matter, slides featuring "I Love Lucy" are bound to be fun.

Esrati does have a point that's relevant to technical communicators, though he could have made it in 15 minutes instead of 45, and it's clearer to me from rereading his presentation abstract than it was from the actual presentation. The rules of how mass media content gets paid for have shifted, and Google, YouTube, and Twitter "get it", while newspapers, record companies, and broadcasters are dying, fighting, or just floundering. (Looks like my former employer, Trilogy Software, is looking to create Newspaper 2.0. They were known for incubating some crazy and crazy-smart start-ups in the dot-com boom era. It'll be interesting to see which category this falls into.)

What Google deeply understands is that the way to make money on the Internet is to deliver laser-targeted advertising that is actually relevant to the people who see it and is shown to them at times when they are interested in just that sort of information. The opportunity for professional communicators, says Esrati, is in creating the content for ads to be shown alongside of. Yay, us.

I've been hearing that "information wants to be free" for a quarter of a century. But Esrati's presentation included a fuller version of that seminal quote from Stewart Brand:

Information Wants To Be Free. Information also wants to be expensive. ... That tension will not go away.

That led me to the original quote from Brand:

On the one hand information wants to be expensive, because it's so valuable. The right information in the right place just changes your life. On the other hand, information wants to be free, because the cost of getting it out is getting lower and lower all the time. So you have these two fighting against each other.

Of course, information doesn't want anything at all. People do the wanting. Receivers (let's not call them "consumers") of information want it to be free, because they want to get it easily and share it with their friends. Producers of information have a motivation to make it expensive, because they see how it can change someone's life, and they think that should be worth something. (They don't always act on this motivation; knowing that information can change people's lives can also motivate giving it away out of altruism.)

Ease of distribution is driving the cost of content to zero. So where is the money coming from that is making Google so successful? It comes from advertisers, and what they are paying for is a kind of information that has historically been extremely expensive to obtain: information about who you are, and what you want, right now.

You give it away, and advertisers pay Google big bucks to deliver it to them. It's the most valuable thing on the Internet. Are you getting a fair trade?

The Botanicalls Kit is one of the coolest new products around: a circuit board and components that, when properly assembled, plugged into AC and ethernet, and sunk into plant soil, can send tweets or text messages about your plant's water needs.



Since this is a DIY kit, the assembly instructions are essential to customer success with the product. I haven't actually tried to follow them (because I haven't shelled out $99 for a kit), but they appear clear and thorough, with lots of step-by-step photos.

But apparently, there are a few pieces of information missing that would be useful, indicated by a posting on the user forums entitled Things I wish you said in your docs .... This kind of feedback is absolutely golden. Rarely do customers express so clearly and explicitly (and in technical detail, in this case) when they need that you haven't given them.

This particular posting has been up for a week with no response from Botanicalls staff, as of this writing. That's a shame. The appropriate response to this kind of feedback is an immediate big fat "Thank you!", along with an explanation of what you're going to do with the feedback. It may or may not be appropriate to include the requested information in the documentation, but the feedback should not go unanswered.

I'm participating in my second FLOSS Manuals event in two weeks. After Winter Camp in Amsterdam, I had a week of "normal" life, and now I'm in Palm Springs, California at the DocTrain West conference, helping lead a book sprint to produce a manual for Firefox.

Right now, we have seven technical writers in a conference room, along with Adam Hyde, founder of FLOSS Manuals, and Chris Hofmann, director of engineering for the Mozilla Foundation. We've had at least that many people contributing remotely. The site shows that 22 people have logged into the site today, though I think one or two of those are working on other projects (that's cool, too).

We're "repurposing" some content from the Firefox Knowledge Base, but also generating new overview and conceptual content.

It's not too late if you want to join in. Just go to http://en.flossmanuals.net, click "Write" at the top of the page, and then click "Register" on the left side to create a login ID. Find the link for Firefox, and see if there are any chapters you'd like to work on. Click "edit" for the chapter, and dig in. There's nifty new IRC chat widget on the right side of the page, so you can talk to everyone else who's participating.