A Techie Tech Writer Blog http://www.janetswisher.com/ Musings on technical communication, open source software, and related topics en-us Nucleus CMS v3.50 Weblog http://backend.userland.com/rss http://www.janetswisher.com//nucleus/nucleus2.gif A Techie Tech Writer Blog http://www.janetswisher.com/ <![CDATA[Mozilla Summit 2010 links]]> http://www.janetswisher.com/index.php?itemid=254 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:
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:

]]> Open Source http://www.janetswisher.com/index.php?itemid=254 Tue, 13 Jul 2010 19:19:49 -0700 <![CDATA[Mozilla Jargon]]> http://www.janetswisher.com/index.php?itemid=248

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.

]]> Writing http://www.janetswisher.com/index.php?itemid=248 Mon, 12 Jul 2010 14:54:34 -0700 <![CDATA[My first post on Mozilla Hacks ]]> http://www.janetswisher.com/index.php?itemid=251 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.
]]> Open Source http://www.janetswisher.com/index.php?itemid=251 Sat, 3 Jul 2010 08:29:42 -0700 <![CDATA[First week at Mozilla]]> http://www.janetswisher.com/index.php?itemid=244 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 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.
]]> Career http://www.janetswisher.com/index.php?itemid=244 Sun, 6 Jun 2010 21:59:26 -0700 <![CDATA[I (heart) content strategy]]> http://www.janetswisher.com/index.php?itemid=240 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.
]]> General http://www.janetswisher.com/index.php?itemid=240 Sun, 2 May 2010 05:37:07 -0700 <![CDATA[Texas Linux Fest and Firefox mini-sprint recap]]> http://www.janetswisher.com/index.php?itemid=235 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.
Janet and Anne talking to Joe Brockmeier at the FLOSS Manuals table

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.
Janet and Anne presenting about FLOSS Manuals

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.
]]> Open Source http://www.janetswisher.com/index.php?itemid=235 Sat, 17 Apr 2010 12:28:33 -0700 <![CDATA[Impromptu Mini-sprint for Firefox, April 11th]]> http://www.janetswisher.com/index.php?itemid=233 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.


]]> Open Source http://www.janetswisher.com/index.php?itemid=233 Fri, 9 Apr 2010 13:13:41 -0700 <![CDATA[Texas Linux Fest, April 10th]]> http://www.janetswisher.com/index.php?itemid=231 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:

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:

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.

]]> Open Source http://www.janetswisher.com/index.php?itemid=231 Mon, 29 Mar 2010 14:32:49 -0700 <![CDATA[I hate "content"]]> http://www.janetswisher.com/index.php?itemid=227
The Free Software Foundation has an interesting take on this term:
... using the word ["content"] as a noun to describe written and other works of authorship ... regards these works as a commodity whose purpose is to fill a box and make money. In effect, it disparages the works themselves. ...

The term “content management” takes the prize for vacuity. “Content” means “some sort of information,” and “management” in this context means “doing something with it.” So a “content management system” is a system for doing something to some sort of information. Nearly all programs fit that description.
My objection is more on the intellectual side. "Content" is just so vague that it could mean almost anything. It implies "stuff that goes inside something else", which could include, say, peanut butter. I think the term "content" has gained currency thanks to web designers, whose primary concern is the form of a design, with the content that goes into the form being somebody else's concern. But for those of us who provide it, the fact that content fits into a form is a secondary feature.

Unfortunately, none of the alternatives is much better. "Information" and "communication" are nearly as broad. "Knowledge" is also broad, and not all content rises to the level of knowledge in the DIKW hierarchy of "goods of the mind". I mention this merely as an excuse to quote T.S. Eliot's The Rock:
Where is the Life we have lost in living?

Where is the wisdom we have lost in knowledge?

Where is the knowledge we have lost in information?
The best alternative to "content" that I can come up with is the slightly longer phrase "content assets". While this still relegates works of authorship to the status of a commodity, it at least makes the concept into a count noun instead of a mass noun, and implies that the commodity has some intrinsic value beyond filling a box.

I realize that "content" is already so prevalent that it's not going to be changed any time soon. But I still can indulge in an inward cringe when I read or hear bare-bones "content", and engage in a private crusade to use "content assets" instead.

]]> Writing http://www.janetswisher.com/index.php?itemid=227 Tue, 2 Mar 2010 19:47:14 -0800 <![CDATA[Article published on open source user assistance ]]> http://www.janetswisher.com/index.php?itemid=222 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.
]]> Open Source http://www.janetswisher.com/index.php?itemid=222 Fri, 1 Jan 2010 10:08:08 -0800