A Techie Tech Writer Blog

My gloss on this picture: If you're confused, go back to the IKEA store and borrow their phone with a really long extension cord, so you can call support from the parking lot.

Last weekend, my husband and I helped a couple of friends, Amanda and Stephen, move into their first owned home. They took the occasion of this move to upgrade and expand their furniture collection with several new items from IKEA. And they hired a service to assemble the furniture. I hadn't realized that such services existed. I'll have to keep that in mind as an alternative career if I get burned out on this tech writing thing. I'm blessed with the right combination of visual, spatial, and motor abilities such that I actually enjoy assembling IKEA furniture. Not everyone is so fortunate (if you want to call it that). As Stephen said, "If I had to do all this, the result would be divorce and me burning the house down." As it happened, a miscommunication meant that the service didn't have time to assemble all the items, so I got to do a couple of them after all.

IKEA is known for keeping their prices as low as possible, and one of the ways they do that is with almost completely wordless pictorial instructions. The fewer words they use, the fewer words they have to pay to translate. The instructions for a bookshelf I recently assembled for myself included a single note that was translated into 18 languages, and therefore took up about half a page. Minimizing text also reduces page count and printing costs. Another way that IKEA reduces printing costs is by using newsprint-quality paper for the instructions in some (but not all) products. Unfortunately, this means that the print quality is also low, and fine details can be difficult to discern for all but the sharpest eyes. Figuring out how pieces fit together can depend on matching the positions of tiny dots in the diagram to those of holes in the physical pieces, so fine details matter a lot.

Wordless instructions may transcend language, but that does not mean that they are universally usable. Some people are just not visual learners. Amanda said, "I can't make sense of those diagrams, but I can do it when Janet explains it." She's more comfortable with verbal instructions than visual ones. In other cases, physical limitations are the issue rather than cognitive style. Stephen is an awesome photographer; he's also visually impaired, so those tiny dots on newsprint are a non-starter. The same can be true for those of us who find our arms getting shorter as we get older and our near-distance vision degrades.

No doubt IKEA has carefully weighed the costs and benefits, and determined that wordless instructions make the best sense for their business. Wordless instructions are sufficient for the majority of their customers, and many of the rest can be helped by phone support. They leave open a market opportunity for furniture assembly services, and IKEA doesn't mind ceding the space, as long as they still sell bookshelves. I wonder if there's also a tiny market niche for verbal instructions to go along with the pictorial ones.

Mozilla Labs has announced the winners of the Contacts Design Challenge, which posed the question to designers of "What are the interesting uses of having a complete list of all your contacts and relationships in your browser, for both local browser applications and services on the web?" The design concepts honored by the judging panel are great, and put forward many useful ideas. Go take a look and then come back here.

None of the design concepts quite addresses the use case that I've recently felt a need for, which is defining groups of contacts from multiple sources, to use within web applications.

Since I've started working remotely from home, I sometimes choose to go sit and work in one of several local coffee shops, for a change of scenery and some live interaction. I know a number of other remote and self-employed workers, who I know also work from coffee shops sometimes. It would be great if we could coordinate so that some of us are at the same coffee shop at the same time. There are web-based services like Foursquare and Yelp that support sending notifications about one's location. But I don't want to require all my coffee buddies to join yet another web service. Some of them are on Facebook, but I don't want to annoy my out-of-town Facebook friends with an update every time I visit a coffee shop. Some of them are on Twitter, but I don't want to end up on Please Rob Me by broadcasting to the universe that I'm not at home. For some of my contacts, I just have an email address, or a mobile phone number that I could send a text message to.

What I want is to not only have all my contacts from various sources aggregated, as in Toby Shorin's design concept, but to define groups of contacts, regardless of the source of the contact. Then, when I want to send an update to members of that group, the software automatically takes care of sending that update to each member of the group, in a way appropriate to the source of the contact. Better yet, sending to those groups should be available to web applications, so that I could tell Foursquare to notify my Coffee Buddies group, just as it currently can update my Facebook or Twitter accounts.

That's what I want. Now I just need to get Mozilla Labs to make it happen.

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:

Just as every industry and domain has specialized jargon, so too do organizations have unique terms for things, activities, and people. Here are some of the terms I'm encountering at Mozilla. This doesn't mean that they're unique to Mozilla, just that I haven't heard them before (or in the case of "awesome", nearly as much).

Chemspill

An emergency release of software, in response to a potentially negative event. This was originally coined with reference to security vulnerabilities, particularly when the hole is actively being exploited by bad guys. However, just recently, Firefox 3.6.6 was released as a chemspill to fix a poor choice for a default setting. This release came quick on the heels of Firefox 3.6.4, which introduced a feature to detect when a plug-in (such as the Flash player) is hanging. In 3.6.4, the default time to trigger this feature was set at 10 seconds, which was too short for many older computers, causing problems for a great many users who upgraded. Hence, a chemspill release of 3.6.6 was done in record time, to change the default to 45 seconds. (The value is configurable, but most users don't know (and shouldn't need to know) how to change it.)

Landing

When a code change is checked into the main trunk of the source control system, it is said to have "landed". I like the imagery of code as birds circling and descending to alight on the (code) tree.

Awesome

This word has the same basic meaning as in common, informal American English, but it's used much more frequently and enthusiastically within Mozilla culture than in the general population. It can range from indicating mild approval to expressing the highest praise, but tends to cluster on the upper end of that scale. Its use is almost always sincere and non-ironic, though it may carry a tinge of self-consciousness. In addition to its usual role as an adjective, "awesome" can also function as a mass noun as in "too much awesome" or "army of awesome". When the Firefox location bar (where you type URLs) was enhanced to support keyword searching and autocompletion based on history and bookmarking, the enhanced functionality was dubbed "the Awesome Bar" by developers, much to the consternation of localizers.

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.

I spent most of last week in Mountain View, California, getting oriented to my new job at Mozilla. Going forward, I'll be working from home in Austin on developer documentation and community for the Mozilla Developer Center. Mozilla, in case you weren't aware, is the people who make the Firefox web browser for desktops and mobile devices, the Thunderbird e-mail client, and a bunch of other cool open-source, web-related technologies. I've barely scratched the surface of what I need to learn in order to be most effective, but I've learned enough to have some idea of where, how, and who to ask my questions.

Mozilla is all about as much openness and transparency as possible. That is reflected in the layout of the Mountain View offices, which are all open-plan desks, with no private offices, even for executives. There aren't even cubicles per se, since the dividers intersect at 120-degree angles, so it's a loose honeycomb of desks. There are lots of small and large conference rooms, which anyone can grab for impromptu as well as scheduled meetings, or phone calls, or just to get away from others' hubbub. All but one of these meeting rooms have glass walls to the rest of the space — transparency again. (The one closed meeting room is because there are always some confidential matters, even in a company dedicated to openness.)

I'm on the Evangelism team, which is part of Engagement, which is part of Mozilla's term for Marketing. I've been in a Technical Documentation team before that reported up to Marketing, but never one whose mission was so explicitly to engage with users (in this case, software and web developers) to create a mutually-beneficial relationship. In this case, there is no group called "Technical Documentation"; rather, within the Evangelism team, there's me and Eric "Sheppy" Shepherd (Developer Documentation Lead), tasked with improving the experiences of developers using web standards and Mozilla technologies.

In the short term, I'll be working on documentation related to Firefox 4, which goes beta later this month. In the longer term, I'll also be working on the transformation of the Mozilla Developer Center into the Mozilla Developer Network — that is, from a collection of documentation into a hub of community and information for the various types of developers that Mozilla serves.

And just in case you're wondering, documentation for ordinary users is provided by the Support at Mozilla (SuMo) team and community. As I said in my article in Open Source Business Resource in January, users don't know and don't care about the difference between documentation and support, as long as they get answers to their questions. Michael Verdi has recently joined that team to manage and enhance the content in the Support Knowledgebase. His post about his first week at Mozilla is much cooler than this one.

Even though I've written here about why I hate the term "content", I'm quite enthusiastic about the emerging discipline known as "content strategy".

The first time I encountered the term "content strategy" was at a UX Intensive workshop run by Adaptive Path in December 2008. Another participant at my table described herself as a "content strategist". When I asked "What's that?", she replied, "It's like a cross between a web designer and a copywriter." At the time, it sounded like title inflation, but I've since learned that content strategy encompasses a great deal more than that.

The field of content strategy emerged as a sub-discipline of web design, when some practitioners realized that the "stuff" in the boxes of a web design deserved at least as much attention as the layout and styling of the boxes themselves. Many credit Rachel Lovinger for first giving voice to this discipline in a March 2007 article in Boxes and Arrows. She described the goal of content strategy as using "words and data to create unambiguous content that supports meaningful, interactive experiences". The notions of content management and content management systems have been around for a long time. They deal with the life cycle of creating, modifying, approving, publishing, and retiring content, (or, ahem, information assets). Content strategy, as its name implies, takes a strategic view of those assets, examining how the goals of the organization are served by the information assets it produces. Many content strategists are primarily concerned with web-based information. However, as technical communicators will immediately recognize, not all of the information that an organization produces is web-based. Therefore, the terms "enterprise content strategy" or "unified content strategy" are sometimes used to refer to applying the content strategy lens to all the externally-facing information of an organization:

A unified content strategy is a repeatable method of identifying all content requirements up front, creating consistently structured content for reuse, managing that content in a definitive source, and assembling content on demand to meet your customers’ needs. — Managing Enterprise Content: A Unified Content Strategy

On a certain level, my reaction to these ideas is "Well, duh. Of course you want to do that." But as an individual technical writer, it's usually easier to complain about how those folks over in Marketing never coordinate with us over here in Tech Pubs than it is to step up to solving content-related problems at an organizational level. Taking the big-picture view is easier said than put into actual practice. On the other hand, I believe that taking the big-picture view is essential for providing long-term value to the organization. Tech writers who focus on just writing the docs will find that their jobs can be done more cheaply in other parts of the world, while those who help ensure that all of the organization's information needs are identified and addressed effectively will continue to find employment.

Content strategy is getting increasing attention from technical communicators, for whom there is a natural progression from managing technical information to managing broader sets of information. The Society for Technical Communication 2010 Summit (getting under way in Dallas this weekend), has a number of items on the program related to content strategy.

• The Content Strategy Institute is a series of four program sessions on content strategy


• The Content Strategy Progression on Tuesday afternoon offers a discussion-oriented format, where attendees pick topics of interest and migrate to their chosen speakers' tables for 20-minute chunks with each one.


• The STC Content Strategy SIG hosts a networking breakfast on Wednesday, and will have a presence at the Welcome Reception on Sunday and Communities Reception on Monday. These events provide opportunities to meet like-minded folks and discuss content strategy issues in a relaxed setting.

I'll be presenting a topic at the Content Strategy progression on building consensus with other content strategy stakeholders. I'll be giving a presentation on Monday entitled Building an Empire from the Grassroots Up, on helping other groups in your organization see the value of content management and content strategy.

I hope to see you in Dallas. If you're not attending the Summit, you can follow attendees' on Twitter with the hashtag #stc10; or you can follow me specifically, @jmswisher.

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.