15 Jun 12: HTML5 media for technical communication

I'm a bit overdue in blogging about my presentation at the STC Summit. My presentation was part of one of the "Beyond the Bleeding Edge" sessions, that showcase new developments in technical communication. These topics are selected just a couple of months in advance of the conference, instead of six or more months in advance, like most of the presentations. (Thanks to Neil Perlin for coordinating the "Beyond the Bleeding Edge" sessions!)

My presentation was "Bursting Open HTML5 Media with Popcorn Maker". You can get the gist from the slides I posted on slideshare:

Popcorn Maker is a GUI tool that is currently in development with support from Mozilla. It will enable non-programmers to create rich, interactive experiences with HTML5 media. The potential of this tool for technical communicators is huge, to be able to index into audio and video, and synchronize them with other content. I showed a few demos that illustrate things that you can do with HTML5 media that might be useful in techcom. Popcorn Maker isn't yet able to create those demos, but it is on a roadmap to be able to do so. For my presentation, I made screencasts of the demos, out of fear of technical glitches in connecting to the websites during the talk. Those videos don't play in slideshare, but there are links to the demos, so you can just play with the sites directly.

If you were at the conference and missed my talk, you'll be able to watch it in the Summit @ a click recordings. If you weren't at the conference, you can purchase the recordings, and see all the presentations, not just mine.

Category: Tools | Posted by: jmswisher | 2 Comments

05 Mar 12: Open and Agile. For tech writers.

I had the good fortune last week to speak at and participate in "Management Day" put on by the Toronto Community of the STC. The purpose of this all-day event was to introduce technical communicators (not necessarily managers) to Agile development through hands-on experience with an open-source project. The workshop on Agile was conducted by Agile consultant Gil Broza, and the open source project that benefited from the participants' work was Ushahidi, which provides software for collecting, visualizing, and mapping issue- or event-related information. My role in the event was to introduce the participants to community-generated content, both from the contributor side and the community-management side.

The day started with presentations by me on community-generated content, Gil on Agile, and Heather Leson on Ushahidi. Then the group broke into teams and did two one-hour iterations of work on Ushahidi's developer wiki, with debriefing sessions after each iteration, and a Q&A at the end of the day. (There were breakfast, lunch, and snacks at various times as well.) I had been skeptical that anything useful could be accomplished in such short iterations, but this was not Gil's first rodeo. He and Heather had come up with several tightly-focused user stories for the groups to choose among to work on. By the end of the day, the two teams had delivered:

So, this event was a win all around. Ushahidi got some professional improvements to their wiki, and the participants got a taste of Agile, a taste of open source documentation, and the good feelings of helping a project that helps people all over the world tell their stories. Many thanks to STC Toronto for hosting, and especially Michele Marques for organizing the event.

Though Gil Broza's slide-less presentation put mine to shame, I've still posted the slides from my presentation, Lessons in Community from Open Source Projects, on Slideshare, as I promised I would.

Category: Open Source | Posted by: jmswisher | 2 Comments

21 Sep 11: Jet Lag and Open Source

Next week I'll be heading to Berlin to attend the European JavaScript conference, and run a documentation sprint in the conference's Hacker Lounge, which Mozilla is sponsoring. This will be my third business trip to Europe since starting at Mozilla a year and a quarter ago. I never expected technical writing to be a jet-setting career, but such are the perks of working for a small but global company.

As I've done for previous trips, I'll be preparing for this trip by using the Ant-Jet Lag Diet, developed at Argonne National Labs. My experience has been that it can't prevent the day of travel from being exhausting, but that I'm able to wake up the following day, rested and adjusted to local time.

I find it unfortunate that the Anti-Jet Lag Diet is not more well-known, despite being nearly thirty years old, and supported by an independent research study. Some of my coworkers travel considerably more than I do, and could definitely benefit from it. Argonne Labs sends out press releases about it every year or so at the start of the summer travel season, but these get relatively little pick-up in the media.

Principles of the Anti-Jet Lag Diet

  • Starting three days before your departure, you alternate "feast" (high-calorie) days and "fast" (low-calorie) days.

  • The food choices on the high-calorie days coordinate to give your body signals about waking and rest times. In particular, on the high-calorie days, you eat high-protein, low-carb foods for breakfast and lunch, because protein is needed by your body for activity. For dinner, you eat high-carb, low-protein foods, because carbohydrates promote sleepiness.

  • The low-calorie days deplete the nutrients stored in your liver, so that your body is forced to use what you consume on the feast days. You eat small meals of less than 700 calories each. (Note that 2100 calories is in the range of consumption normally recommended for most adults, so "low-calorie" is relative.)

  • Consume caffeine only between 3:00 and 5:00 p.m., (in other words, the mid-point of your waking hours), when it is least likely to disrupt your sleep patterns.

  • Alcohol is highly variable in its effect on sleep patterns, so it is best to avoid it while following the plan.

  • The day of travel is a low-calorie day.

  • While in transit, as much as possible, sleep (or rest) and be active according to the normal schedule of the target time zone.

  • At the target breakfast time, have a high-protein breakfast.

  • Stay awake until evening at your destination.

An Example

I'm going to be leaving Texas (US Central Time, UTC-5) on Wednesday afternoon, arriving in Berlin (Central European Time, UTC+2) around mid-day Thursday. I'll start the diet on Sunday, three days before my departure.

(day -3)
(day -2)
(day -1)
(travel day)
Breakfasthigh-proteinlight foodshigh-proteinlight foodshigh-protein, on Berlin time
Lunchhigh-proteinlight foodshigh-proteinlight foodsAs normal
Dinnerhigh-carblight foodshigh-carblight foodsAs normal

Tips and Observations

It's easier to follow the diet before departure than while traveling. In fact, it's challenging to follow any restricted diet while traveling, as your food choices are not as much under your control as usual. It can be challenging to find a high-protein breakfast in some parts of Europe. Avoiding alcohol for the last three days of your trip might cramp your enjoyment of your trip. As a minimal alternative, you can make your day of travel a low-calorie day, and then follow the other suggestions for adjusting to your target time zone.

When traveling from North America to Europe, flights are usually "overnight", and the flight attendants usually serve breakfast an hour or so before landing, which fits conveniently with this plan. Going the other direction may involve eating two breakfasts in one day. I carry high-protein nutrition bars, so that I can be sure to eat the right kind of nutrients at the right times.

If you request a special meal type (vegetarian, kosher, whatever), it flags you as special in the flight attendants' minds. They may therefore be more accommodating when you make other special requests, like reheating a meal that you didn't eat at the time when they served it.

I'm not addicted to caffeine, so the restrictions on it in this plan are not a problem for me. If you are addicted to caffeine don't torture yourself. Take only enough caffeine to keep the headaches at bay, except during the very middle of your waking hours.

The Open Source Angle

In 2004, Argonne granted an exclusive license for software for calculating timing of meals while in transit, to AntiJetLagDiet.com, which offers it as a web-based service or an iPhone app. This has led to a perception, reflected in this LiveStrong.com article about the diet, that the software is required in order to use the diet, which is absolutely not true. The software may save you a little confusion if you're crossing international date line, but the essentials of the diet are nutritional, not technological. The diet was around long before the software. When I first heard about it while I was in college, I sent off a self-addressed stamped envelope (remember those?) and received a laminated card with a summary of the plan, no software required.

It seems to me that, rather than licensing the software to a single commercial company, Argonne should have released the software as open source. Since it was developed at a taxpayer-funded government research lab, the software should be freely available. Furthermore, I think that would have led to it being more widely used and known, as well. The software doesn't quite provide enough functionality to stand on its own, but as an open source library, it could have been incorporated into other programs as an added feature, for example, travel planning and review sites. Imagine a mobile app that not only reminds you that today is a high-calorie day, but shows you the nearest restaurant where you can order a "full English breakfast". A sadly missed opportunity.

Category: General | Posted by: jmswisher | 1 Comment

10 Aug 11: MDN doc sprint, August 12-13, online and in South Austin

One of my responsibilities at Mozilla is organizing documentation sprints to work on developer-oriented content for the MDN Documentation Center. Since last fall, we've done four doc sprints, with two that had in-person gatherings, and two that were all virtual, that is, with everyone participating "remotely".

We're doing another doc sprint this week, from Friday through Saturday, August 12 to 13. This one is virtual, in that there's no centralized gathering. But that doesn't preclude distributed local gatherings. I'll be hanging out at Fair Bean Coffee on South 1st Street in Austin on Friday and Saturday afternoons. Please come join me if you're interested in seeing what a doc sprint is like, and pitching in. Here are links to Plancast for both days:

The focus of this sprint, as usual, is open web technologies such as HTML, CSS, and JavaScript. (Though if you have expertise in Mozilla-specific topics, you're welcome to work on those, too.) Don't worry about having to write something from scratch. If you're a writer or editor, you can check topics that are tagged as "Needs Editorial Review"; if you're a web techie, you can check for "Needs Technical Review" or "Needs Code Examples".

If you're not in Austin, you can still participate on your own. If you happen to be in Bordeaux or Taipei, you can join doc sprint meet-ups in those cities. Or you can start your own meet-up.

Details about the doc sprint are on the Mozilla wiki. You'll need to register for an account on MDN, and get a way to connect to IRC to chat with other sprinters.

I hope to see you at the sprint, in the flesh or online!

Category: Open Source | Posted by: jmswisher |

21 Apr 11: Bill Hicks's Principles of Comedy applied to public speaking

Last night I went to a screening by the Austin Film Society of American: The Bill Hicks Story, which opens at the Alamo South Lamar on Friday. This is an intimate biopic of Bill Hicks, based on interviews with the comedian's family and close friends, and includes some rare archival footage (such as this clip of Hicks performing as a teenager). I highly recommend this film if you're a fan of Bill Hicks, or of stand-up comedy, or of people who tell the truth.

Among the special treats for the audience at the AFS screening, the filmmakers gave away cards printed with "Bill Hicks's Principles of Comedy". With just a few small wording changes, these apply to public speaking in general (and in some cases, life). So, here they are, with my edits marked, in hopes they will be helpful:


(Printed out and posted by Bill on the wall at the Laughing Skull in Atlanta.)

  1. If you can be yourself on stage nobody else can be you and you have the law of supply and demand covered.

  2. The act prepared talk is something you fall back on if you can't think of anything else to say.

  3. Only do what you think is funny important, never just what you think they will like, even though it's not that funny important to you.

  4. Never ask them "Is this funny important?". You tell them this is funny important.

  5. You are not married to any of this shit* — if something happens, taking you off on a tangent, NEVER go back and finish a bit point, just move on.

  6. NEVER ask the audience "How you doing?" People who do that can't think of an opening line. They came to see you tell them how they're doing, asking that stupid question up front just digs a hole. This is the Most Common Mistake made by performers. I want to leave as soon as they say that.

  7. Write what entertains fascinates you. If you can't be funny be interesting. You haven't lost the crowd. Have something to say and then do it in a funny way.

  8. I close my eyes and walk out there and that's where I start, honest.

  9. Listen to what you are saying, ask yourself, "Why am I saying it and is it necessary?" (This will filter all your material and cut the unnecessary words.)

  10. Play to the top of the intelligence of the room. There aren't any bad crowds, just wrong choices.

  11. Remember this is the hardest thing there is to do. If you can do this you can do anything.

  12. I love my cracker roots. Get to know your family, be friends with them.

*While I'm embarrassed to be censoring Hicks's text, I want this to be readable by people behind corporate nanny-filters.

Category: General | Posted by: jmswisher | 5 Comments

12 Apr 11: Busy, busy

Much has happened, personally and professionally, since I last had time to post here.


  • I coordinated two doc sprints for Mozilla Developer Network, in January and in April.
  • My husband and I adopted a one-year-old standard poodle, whom we've named Jazz.
    Jazz the poodle
  • I attended South by Southwest Interactive, which was five intense days of meeting and talking to people in the web biz. Mozilla sponsored the Austin JavaScript party, which raised 683 pounds of food for the Capital Area Food Bank. We also got five guys in kilts to wear MDN t-shirts.
  • Mozilla released Firefox 4 for desktop and mobile. Then the company brought all its paid staff members from all over the world together for a week of face-to-face meetings, including a side-trip to Las Vegas.
  • Meanwhile, I'm managing the STC Austin Salary Survey. If you worked as any kind of technical communicator in the Austin or San Antonio areas in 2010, please take the survey, while your income numbers are fresh in your mind from your tax return. This is the only salary survey for technical communicators that focuses specifically on Central Texas, so please help our professional community by participating.
  • I'm speaking at the STC Houston chapter on April 12th (that's today) on Wikis and Community-Contributed Content.


Once, again, please please take the salary survey, if you are in Central Texas!

Update 2011-0413: I forgot to mention that Anne Gentle and I had a FLOSS Manuals table again this year at Texas Linux Fest. (Like I said, a lot has happened lately.) We sold paper copies of Introduction the GNU/Linux Command Line and How to Bypass Internet Censorship. One person that Anne talked to said that he had gotten a Linux-based job after reading the Command Line book after last year's TXLF. Woo!

Category: News | Posted by: jmswisher |

24 Jan 11: Doc sprint for open web standards, January 28-29, 2011

I am organizing a documentation sprint for web standards docs on the Mozilla Developer Network site, taking place this Friday and Saturday, January 28 and 29.

If you've been wanting to find out what a doc sprint is like, this is a great opportunity. It will be a "virtual" sprint, so no travel is involved. You can join in from wherever you are.

We especially need people to write introductory-level material on HTML, CSS, and JavaScript. One piece of feedback I hear about the content on MDN is that it's great for intermediate to advanced web developers, but has little for brand new web developers. In contrast, some other tutorial sites have very accessible intro content on web-development topics, but that content may be out of date or misleading (which is not apparent to newbies).

Please help us change that! You don't have to tackle all of HTML, etc. If you can come up with a small but realistic example of a set of features, and then explain how the example works, that would be a significant help.

For details on the sprint, see my post on the Mozilla Hacks blog: Write some docs, get an MDN t-shirt. That post has a link to the wiki planning page where you can sign yourself up to participate.

For "virtual presence" during the sprint, we'll be using IRC for real-time text chat. There are many IRC client programs available. (The protocol actually predates the World Wide Web, so many of them are command-line driven.) If you want to help with the doc sprint and you haven't used IRC before, you might want to take a little time to get familiar with it before the sprint starts. If you need some help getting started, feel free to contact me at my Mozilla e-mail address (jswisher at mozilla dot com).

And finally, even though this is a "virtual" sprint, if you are in Austin, there's nothing to stop us from getting together at a coffeeshop for some local in-person co-sprinting. Drop me an e-mail, and let's work something out.

Category: News | Posted by: jmswisher | 1 Comment

19 Jan 11: Links for "Before You Pick a Wiki"

Update June 21, 2011: The slides from this presentation are now available on Slideshare: (Things to Think About) Before You Pick a Wiki

This post contains resource links for my presentation "Before You Pick a Wiki". I'm giving this presentation a few times:

Since the presentation is likely to evolve, I'm not sharing my slides until after the Summit in May. However, I'm referring audiences to this post to find resources that I reference in the presentation. I'll update this post as I update or change the presentation.



Category: News | Posted by: jmswisher |

06 Dec 10: Vote for Booki for the Drumbeat/transmediale Open Web Award

For nearly two years now, the FLOSS Manuals project has been working on developing a new platform to support not just its own work, but collaborative authoring and publishing of open content in general. This platform is called Booki (for "book wiki"). I've alluded to Booki occasionally on this blog, but haven't described it in detail.

Booki is designed to help people collaboratively write books online. It builds on the knowledge that the FLOSS Manuals project has gained from trying to adapt existing wiki software to support book creation and publishing, but starts fresh as purpose-built open source software. You can learn about the vision and planned features of Booki from its design document on the FLOSS Manuals site. Out of the box, it supports contributors working together to create open content, tracks attributions for licensing purposes, provides facilities for remixing content, and publishes to multiple output formats, including HTML, print-formatted PDF, and various e-book formats. The Booki blog has a great series of tutorial articles introducing Booki's features.

The development investment in Booki is starting to bear fruit. An instance of Booki has been in beta testing at booki.cc for several months now. You can test-drive Booki by creating a login on that site, and then creating or editing open content as your heart desires (which can be any kind of "comprehensive text", not just software manuals). The Booki software has reached a point of maturity and stability such that the FLOSS Manuals project is beginning the migration of its existing manuals and production website to a Booki instance.

Sounds great, huh? Want to help?

Booki has been nominated for a Drumbeat/transmediale Open Web Award. You can help support the completion of Booki by taking two very simple steps:

  1. Register for an account on the Drumbeat site. This won't subject you to any e-mails (other than sign-up confirmation) unless you opt in to the Drumbeat monthly newsletter. Drumbeat is a project of Mozilla, which is very serious about protecting your privacy.

  2. Click the Vote button on Booki's project page.

That's it! As an optional step, you can leave a comment about why you think Booki is good for the open web. Comments and other project activity will be considered by the judges in addition to the raw vote numbers. Voting is open until February 4, 2011, and the winner will be announced at the transmediale awards ceremony on February 6, 2001.

But why wait? Vote now while you're thinking about it.

Category: Open Source | Posted by: jmswisher |

04 Nov 10: Links round-up from Learning, Freedom, and the Web

I told some people that I would tweet and blog from the Drumbeat Festival for Learning, Freedom, and the Web. However, I've far too busy engaging with people at the festival in meat-space to think much about engaging virtually. Search on Twitter for #drumbeat if you want to follow those who are virtually engaged at the festival.

Here is a (far from exhaustive) list of links I've collected for projects and people I've encountered, mostly from the opening Science Fair. Draw your own connections and conclusions.

Category: Open Source | Posted by: jmswisher |