A Techie Tech Writer Blog

I spent most of last week at the Mozilla Summit in Whistler, British Columbia. I'd like to have something pithy and insightful to say about it (because I hear that my reflections on conferences make my blog "come alive"), but mostly I am overwhelmed and speechless at the combination of people and technology that I experienced. The Mozilla Summit is an invitation-only event that brings together Mozilla employees, community leaders, and selected friends of Mozilla for three days of sharing, connecting, and planning. There were inspiring keynote speeches, mind-blowing demos, informative and productive breakout sessions, five-minute lightning sessions on a huge variety of topics, a "science fair" of even more demos, a "world expo" with over 30 locales represented, and fabulous food throughout.

Rather than try to express it myself, here are a few links related to the Summit:

• A video of one of the keynote demos. This video is a capture of the animation that was rendered in real time at the Summit, with live Flickr and Twitter feeds. The video unfortunately does not include the perfect tweet from @sheppy: Fairly sure some of this technology was stolen from crashed alien ships. It also demonstrates that in the world of new open web standards (HTML5/CSS3/WebGL/etc.) motion sickness is the new blink tag.


• Intern Brian Louie recaps day 3, including the breakout session that I helped lead on the future of the Mozilla Developer Network.


• Summary of the Summit by Channy Yun, a community member from South Korea.

Whistler is a year-round resort town, but it's best known for snow sports (despite disappointing snowfall for the Winter Olympics). It was refreshing to go to the top of Whistler mountain for the final night's dinner and party, and see snow in July:

Mozilla Hacks is Mozilla-run blog for developers that highlights innovative uses of Firefox and the open web. I've posted my first entry, Help us set priorities for docs. As I mention in the post, Mozilla is planning to start doing doc sprints to improve the developer-oriented content on the Mozilla Developer Network site. So we're soliciting input from the developer community on what their greatest documentation needs are.

It's exciting for me as a techwriter to be able to get direct feedback from members of the documentation audience, and not have to go through intermediaries such as support, consulting, or sales. I no longer have to guess about what they want, because, believe me, they are more than willing to express themselves! Votes are already pouring in to the Dev Doc Priorities forum. Users have 10 votes, which they can spread around multiple topics, or pile them all on one. As I write this, "Multithreading in JavaScript" is in the lead, but "HTML Reference" is only a few votes behind.

Now that I've had a week to recuperate, I can give a recap on last weekend's Texas Linux Fest and Firefox mini-sprint. Here are my personal highlights.

FLOSS Manuals table

Anne Gentle and I staffed a vendor table for FLOSS Manuals, at which we gave away stickers and sold books that were written through FLOSS Manuals. Anne had planned to set up some FM books on Amazon CreateSpace to print and take to sell at TXLF. However, that didn't get ironed out in time, so she had copies made at a local print shop instead. More expensive per copy, but actually ready in time for the Fest. She also got a roll of 500 stickers printed, to give away. (Many thanks to Anne for getting all that stuff printed!)

Our table was at the back of the vendor space, near the ladies' room. That was convenient for us, and didn't seem to reduce the traffic to the table. We got lots of interest at the table, with a number of people saying "I had no idea such a thing existed". So we have definitely spread the word.

Presentations

Anne and I gave a presentation about FLOSS Manuals, highlighting how it can help open source projects address their documentation needs. Anne has put the slides on Slideshare.


I gave another talk with David Cramer about how non-programmers can contribute to open source projects. We changed the title after the programs had been printed to "Collaborating with Non-programmers", which sounds less one-sided than the original title.

I didn't attend many of the other talks during the Fest, as I was staffing the table. I saw the first part of Joe 'Zonker' Brockmeier's opening keynote, "A Musical Guide to the Future of Linux", in which he compared various operating systems and Linux distributions to music bands. Unfortunately, I had to go set up for my talk with Anne, so I didn't hear the end, in which he explained how Linux itself could become less like the Ramones, and more like the Beatles.

I also saw Amber Graner's talk on her experiences as an "NTEU" (non-technical end user) of Ubuntu. Amber may be non-technical, but she is nonetheless a geek (that is, one who combines intelligence and obsession). She dove into the Ubuntu community headfirst, and a year and a bit later is a team leader of a local ("LoCo") Ubuntu group and of the Ubuntu Women Project, a blogger for Ubuntu User magazine, and an editor for Ubuntu Weekly News. She has also been to at least six Linux, Ubuntu, or open source conferences or events. She's certainly proof positive that there can be space for non-technical folks in open source. Non-obsessed folks, that's another question.

The closing keynote was by Randal Swartz. It highlighted many of the same points as David's and my talk about ways to contribute to open source other than programming. However, his talk had more personal examples and anecdotes about Larry Wall, Linus Torvalds, and Richard Stallman.

Firefox mini-sprint

I skipped the post-Fest pub crawl on 6th Street, though I did go to dinner at Chuy's, organized by Joe Cooper of Webmin. Our group gradually grew from about six to about two dozen, such that we didn't get seated until after 9pm. It was a nice chance to talk to an assortment of attendees from the Fest, including some fellow IBMers.

I was glad, then, that I hadn't scheduled the Firefox sprint to start until 11am on Sunday. The idea of doing a mini-sprint after TXLF came from Joe Brockmeier, who gave the opening keynote. He's a technology journalist and until recently was a community manager for openSUSE. I picked the Firefox update as a smallish chunk of work that could potentially be done in a day.

I announced the sprint on the FLOSS Manuals discussion list, on my blog, on the TXLF mailing list, and on the Mozilla Support Contributors Forum. Zonker mentioned it during his keynote, and I had mini-flyers at the FM table with the
details. I had no idea who would show up besides Zonker and me.

We had two additional people come to the coffeehouse to help with the sprint, and two remote contributors. I got email from one person who looked for us at the coffeehouse and didn't see us :-( and there was one person who came to hang out and sprint on a different project (I had extended that invitation in the TXLF announcements).

I didn't have much time to prepare for the sprint, since I was also preparing for my talks. So my first task during the sprint was to go through the list of new features in Firefox 3.6 and identify where that info needed to be added to the FM manual. I found about 15 tasks. By the end of the sprint on Sunday, about one third of those had been completed.

So, there is more work to do before the Firefox manual is up to date. If you're interested, please take a look at the previous post to see how to get started. Then look at the ScratchNotes page, pick something to update, and then mark it done when you're done.

I think the sprint worked out reasonably well, given that it was organized at pretty much the last minute (e.g., after out-of-towners had made their travel plans). With more advance notice, we might have gotten more people. But at least a few people got a chance to try out the FLOSS Manuals tools and process.

I wrote last year about the book sprint for Firefox that I helped coordinate last year as part of DocTrain West. The book that we created in two days in March 2009 was updated by Firefox folks for Firefox 3.5 in July 2009.

At very much the last minute, I'm putting together a one-day mini-sprint to update the Firefox book to correspond to Firefox version 3.6.

It will be on Sunday, April 11th (the day after the Texas Linux Fest), from 11am to 4pm Central US time (OTC-6).

Everyone is welcome to join in, for whatever amount of time you can spare.

If you're in Austin, meet us at Genuine Joe Coffeehouse, 2001 West Anderson Lane. Let me know [janet at flossmanuals dot net] if you're going to show up, so I can arrange enough space for everyone.

If you're not in Austin, you can join us remotely on the FLOSS Manuals site and on IRC (irc.freenode.net #flossmanuals) — that IRC channel is embedded in the flossmanuals site, but you can use any client you prefer.

How to participate:

1. Download and install Firefox, if you don't have it already.


2. Register for a FLOSS Manuals login, if you don't have one already.


3. Review the list of what's new in Firefox 3.6. Most can just be added to existing chapters.


4. Go to the Write section for Firefox.


5. Pick a chapter that you want to update and click the "edit" link.

The first-ever Texas Linux Fest is coming up on Saturday, April 10th. It'll be in Austin at the Marchesa Events Center near I-35 and FM 2222.

I'll be co-presenting two sessions:

• Documentation Needs? How FLOSS Manuals Can Help with Anne Gentle, about the FLOSS Manuals project
• Benefiting From the Skills of Non-programmers with David Cramer.

Anne and I will also be staffing a booth for FLOSS Manuals, selling a few titles from the FLOSS Manuals catalog that we think will appeal to this audience:

• Introduction to the GNU/Linux Command Line
• How to Bypass Internet Censorship
• Open Translation Tools

We'll also have bunches of FLOSS Manuals stickers to give away.

Check out the other sessions on the program. There are talks for the open-source curious as well as Linux die-hards. Register at the ultra-cheap "enthusiast" rate of $15, or the quite reasonable "supporter" rate of $40, which includes a T-shirt and a goodie bag. You can also pay at the door, but rates will go up by $5 on the day-of.

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.

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.

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.