A Techie Tech Writer Blog

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.

Meal	Sunday (day -3)	Monday (day -2)	Tuesday (day -1)	Wednesday (travel day)	Thursday
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.

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:

• MDN doc sprint, Austin, day 1


• MDN doc sprint, Austin, day 2

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!

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:

BILL HICKS's PRINCIPLES OF COMEDY

(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.

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

Recent

• 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.
  
• 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.

Upcoming

• 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!

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.

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.

References

• 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

Resources

• WikiMatrix compares features for 128 wiki engines (at last count).


• 10 Questions: A Checklist, from Alan Porter's book


• Wikipatterns.com


• Developing Technical Documentation on a Confluence Wiki


• DITA2wiki


• 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

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.

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.

• 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.

This is a guest blog post from David Cramer, who is a Staff Technical Writer at Motive, an Alcatel-Lucent company, and is also a self-described XML-for-documentation tools geek.

---

Suppose you're writing context-sensitive help for a cross-platform application that's translated into six languages, including Japanese. If you were writing help for an Eclipse-based application, it would be easy. The Eclipse user assistance infrastructure is powerful and flexible. The format is simple, has internationalization built-in, and can be produced from a variety of formats including DocBook, DITA, and some traditional HATs (Help Authoring Tools). Even if you’re writing help for a native Windows application, you would just produce a .chm file and leave it to the localization vendor to figure out how to produce the Japanese version. But often you find yourself writing help for a Web application and in that case, the choice isn’t as clear.

Sure, you can now create a .war version of an Eclipse infocenter, but that’s probably overkill for a help system that’s going to contain a single document. Moreover, many tech writers won’t have the technical skills to get it to work and even if they do, they’ll probably meet resistance from the developers. Your project manager might be worried about taxing the app server’s performance or worried that if they support another app server they’ll have trouble getting your little war file to work in the new environment. Often developers just want a bundle of HTML, CSS, and JS files from their writers and nothing more complicated.

Now, there are a few cross platform formats that offer all the stuff you expect to find in a help system: a table of contents pane on the left with a search tab and maybe an index tab on the left. Ideally it will highlight the search results in the page. The search needs to support stemming and needs to support languages other than English, including Chinese, Japanese, and Korean (“CJK”). CJK is hard, by the way, because those languages don’t have spaces between their words, so the strategy used by most client-side search engines fails. The indexer can’t easily create a list of terms in the set and indicate on which pages those terms occur, because there’s nothing to use as a delimiter in tokenizing the words. In addition to all that, you might also want a button to hide the table of contents to maximize the content area and you certainly want a way to sync the contents of the table of contents with the content so the user will be able to see where a topic occurs in the table of contents, when jumping from topic to topic via cross references or other links. Oh, and you must have a way to deep-link into the help set so you can do contextual help. It’s not such a hard thing, but for too long our options have been limited to a few commercial tools of questionable overall quality. In fact, on this very blog, Janet has called this the “holy grail”.

Enter the Google Summer of Code 2010 and Kasun Gajasinghe, a student at the University of Moratuwa in Sri Lanka. This past spring, nudged along by Dick Hamilton and Stefan Seefeld, the DocBook Open Repository project applied to be a mentoring organization for the first time. Why hadn’t we done this before? No idea. I guess we all had our heads down in our own problems and it didn’t occur to anyone that Summer of Code would be a great way to advance DocBook development while introducing some bright students to the ins and outs of open source development. In any case, I’m very happy that Dick and Stefan got the ball rolling and were willing to administer our participation in GSoC as well as mentor students and especially happy that Kasun submitted his proposal to provide webhelp for DocBook.

The features that he implemented include:

• Full text search with:
  
  • Stemming support for English, French, and German. Stemming support can be added for other languages by implementing a stemmer.
  • Support for Chinese, Japanese, and Korean using code from the Lucene search engine.
  • Search highlighting that shows where the searched for term appears in the results.
  • Search results can include brief descriptions of the target.
• Table of contents pane with collapsible TOC tree.
• Auto-synchronization of content pane and TOC.
• TOC and search pane implemented without the use of a frameset.
• An Ant build.xml file to generate output.

Kasun's work from his Summer of Code project is now part of version 1.76.1 of the DocBook XSLs. Please take a look and share your thoughts below.

Thanks, Janet, for letting me hijack your blog!

My recent visit to Paris coincided with the strikes and protests in France over raising the retirement age for French workers. The hotel where I stayed is a few blocks from the place de la Bastille, which, due to its place in history, is a popular location for political protests. As so it was that, returning from sight-seeing one day, I found myself on the fringes of a protest march. The entire Bastille roundabout was blocked to traffic as the march proceeded south on Boulevard Beaumarchais, skirted the traffic circle, and headed west on rue de Faubourg Saint-Antoine.

There were, as you might expect, marchers in the street with banners, trucks with loudspeakers, and even a brass band, along with spectators watching from the sidewalks. I noticed that many people had put stickers with slogans on their clothing — both cheaper and easier to read than lapel buttons. (That I'd never seen this before may just indicate that I haven't been to a protest march in mumblety years.)

One communication technique that caught my attention was plastic tarpaulins covered in comics-style cartoons, laid out on the cobblestones of the plaza.


(Click for larger views)

Cartoons have a long history of political purposes. In fact, almost as soon as woodcuts and engravings met the printing press, they were used to support Martin Luther's critique of the Catholic church. The multi-panel comics-style of cartooning is less common than single-frame cartoons for political commentary, though Doonesbury is a venerable exception.

One aspect that was interesting to me about these French cartoons was that they were not just political, but instructive. That is, rather than simply satirizing the subject, they attempted to explain the protesters' arguments as well as to persuade. The cartoon in the first image above is titled "Simple comme un dessin" — "Simple like a drawing". In that respect, they tie in to the increasing use of cartoons in technical communication. Google famously published a comic book by noted comics artist Scott McCloud to explain the technical architecture of the Chrome browser. A cartoon is one of several media used by Richard Milewski for a Mozilla user education campaign on password security. And Alan Porter of the 4Js Group has carved out a niche developing comics for educational and business purposes.

The other intriguing aspect was the physical medium: marker on plastic tarps. The choice is very appropriate to the audience and usage context. The cartoons convey more information than a banner or sticker, but take less time to absorb than a speech. The tarps provided a way to share the information with a large number of people, with a lower environmental impact than printed fliers, which would have become trash immediately after (if not before) being read. They provided a shared experience of reading, as there were usually a number of passers-by reading them at any given time. They also would have survived the rain that threatened to drop during the march.

Technical communication lessons are everywhere, if you just look for them.