15 Jun 12: HTML5 media for technical communication
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.
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:
- A reorganization of the Ushahidi Platform documentation (done live in the wiki)
- An outline for procedural documents
- Recommendations for improving the top-level categories of the Ushahidi development wiki
- A brainstormed list of suggestions and guidelines for documentation writers
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.
21 Sep 11: Jet Lag and Open Source
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.
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.
|Breakfast||high-protein||light foods||high-protein||light foods||high-protein, on Berlin time|
|Lunch||high-protein||light foods||high-protein||light foods||As normal|
|Dinner||high-carb||light foods||high-carb||light foods||As 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.
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:
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!
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:
BILL HICKS's PRINCIPLES OF COMEDY
(Printed out and posted by Bill on the wall at the Laughing Skull in Atlanta.)
- If you can be yourself on stage nobody else can be you and you have the law of supply and demand covered.
actprepared talk is something you fall back on if you can't think of anything else to say.
- Only do what you think is
funnyimportant, never just what you think they will like, even though it's not that funnyimportant to you.
- Never ask them "Is this
funnyimportant?". You tell them this is funnyimportant.
- You are not married to any of this s
hit* — if something happens, taking you off on a tangent, NEVER go back and finish a bitpoint, just move on.
- 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.
- Write what
entertainsfascinates 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.
- I close my eyes and walk out there and that's where I start, honest.
- 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.)
- Play to the top of the intelligence of the room. There aren't any bad crowds, just wrong choices.
- Remember this is the hardest thing there is to do. If you can do this you can do anything.
- I love my cracker roots. Get to know your family, be friends with them.
12 Apr 11: Busy, busy
- 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.
- 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.
- I'll be speaking at the STC Technical Communication Summit, May 15-18, in Sacramento. I'll be giving my presentation on picking a wiki again, for those who missed seeing it in Austin or Houston. And Eric Shepherd and I will talk about Radically Open Documentation, what it's like to live on the bleeding edge of community-contributed content.
- I'm also speaking at the Open Help Conference, June 3-5 in Cincinnati, on how Mozilla engages developers in our documentation.
- Immediately following the Open Help conference, there will be another MDN doc sprint, with in-person meeting in Cincinnati. Details forthcoming on the Mozilla Hacks blog.
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!
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.
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.
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:
- STC Austin chapter, Thursday, January 20
- STC Houston chapter, Tuesday, April 12
- Technical Communication Summit, May 15 to 18
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.
- Anne Gentle, Conversation and Community: The Social Web for Documentation
- Stewart Mader, Wikipatterns
- Jacob Neilsen, Participation Inequality: Encouraging More Users to Contribute
- Alan Porter, WIKI: Grow Your Own for Fun and Profit
- Ann Rockley, Managing Enterprise Content: A Unified Content Strategy
- WikiMatrix compares features for 128 wiki engines (at last count).
- 10 Questions: A Checklist, from Alan Porter's book
- Developing Technical Documentation on a Confluence Wiki
- Exporting Confluence Pages and Spaces to PDF
- MediaWiki Pdf Export extension: See wiki.service-now.com for an example of a wiki that seems to use it.
- Creative Commons licenses
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:
- 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.
- 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.
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.
- The Prototype Project
- Seeks: crowd-sourced curation of search results
- Open Knowledge Foundation
- Connexions: open course materials
- Cohere: tool for collaborative learning, sense-making, and critical thinking
- Free Technology Academy
- jPlayer: open web media plugin for jQuery
- Big Fun Arts
- HASTAC's proposed Master's degree in Knowledge and Networks at Duke University
- Learning without Frontiers
- Scrunchup, web magazine for young designers and developers. Co-founder Anna Debenham gave an eye-opening keynote about the sad state of IT education in the UK.