In a previous post, I discussed the problems we encountered when considering translating our entire MediaWiki-based documentation suite. I talked about how to get content out of the wiki for translation, and then get translated content back to our users.

In this post, I want to discuss translation and globalization requirements more generally, and how our small, agile doc team, working in MediaWiki, handles each requirement. Fulfilling these requirements results in lower translation costs and easier translation:

• Provide a medium for the translated documentation that accommodates text expansion
• Use preformatted styles
• Minimize the amount of text to be translated
• Minimize content churn
• Write in a style that allows easy translation

A medium for the translated documentation

Full marks on this requirement. Delivering the translated documentation in a Japanese sister wiki will work well. We also integrate our documentation with our software as JavaHelp, and there are no issues with text expansion in either medium.

Preformatted styles

Again, no issues here. MediaWiki provides heading and formatting styles that are preserved in the XML export, so no one needs to waste time on formatting the translated text.

Minimizing the amount of text

I didn’t have time to write a short letter, so I wrote a long one instead. – Mark Twain

Here’s where the slope gets slippery. Shorter takes longer. With a small team under constant pressure to keep up with agile development, it’s hard to find the time to write concisely. It’s also hard to find time to deal with legacy content.

Minimizing the amount of documentation makes sense for the English version as well as translations. And it makes for easier maintenance, too.

Minimizing churn

There are two opportunities for content churn: during development, and after the release.

During development. Ideally, we’d provide an initial drop to the translators at Beta, and pledge that we’re something like 80% complete. But in agile development, features are constantly refined as a result of testing and customer feedback. Features are added to the release as resources permit, and as product management becomes aware of new customer requirements. With a small team, we work on documenting features right up to the release date. Our development, test, and product management teams review the docs whenever they have time. And as perfectionists, we just can’t resist editing… and re-editing. An agile wiki is a highly flexible creature. But churn is its middle name.

After the release. We continue to fix problems we find in the English documentation, and our customers can edit too. That’s the whole point. Presto: The translation is out of date.

Easily translatable style

We’ve adopted a casual, conversational, humorous style as an attempt to engage our users. But this type of style can be difficult to translate. It can also be difficult for ESL readers to understand. And even non-North American English speakers might find our humor… unfunny.

Here are just a few things we need to do:

• keep sentences short
• simplify the grammatical structure
• avoid idioms and jargon
• create a more extensive glossary
• avoid text in graphics

So, in our spare time, we’re updating our style guide, and when that’s done, we’ll be creating a review checklist for translation and globalization requirements. Our style guide will be funny, because so far, no one has asked us to translate it.

Good reading

I found the article “Maintaining Documentation Across Several Languages” helpful in my research.

We moved all of our user documentation from Author-it to MediaWiki a few releases ago. At that point, we translated only a part of our documentation to Japanese – the help pages for detected issues. For these wiki pages, we used MediaWiki language templates to display language links at the bottom, and we copied-and-pasted the translated text.

For our most recent release, we expanded the translation effort. This meant more copy-and-paste – from the wiki to Microsoft Word, to send to the translator, and then from Word to the wiki, when we received the translated text.

We discovered that the language templates don’t work when the page title contains a backslash, so we had to change some page titles – for example, some of our page titles include “C/C++”. In MediaWiki, changing a page title means manually editing all pages that link to that page – not so fun.

Recently, one of our product managers (who’s been doing double-duty as localization coordinator – a.k.a. Copy-and-Paster Extraordinaire) said that he needed to get a quote on translating the entire wiki into Japanese. Warning bells went off in my head. I wondered:

• How do we ensure that shared content is translated only once?
• How do we get the material out of the wiki to send to the translator for a quote and translation?
• Where do we put the translated text?
• How well does our documentation lend itself to translation?

Handling shared content

We use MediaWiki templates to “single-source” documentation. Much as in traditional documentation platforms, wikis allow you to reuse content. For instance, we use a template for the current release number, so that we have to edit it only once per release. We also use templates for information that’s identical across multiple Klocwork tools – from phrases to multiple paragraphs.

Getting the content out of the wiki – attempt #1

Clearly, copy-and-paste for 435 wiki pages plus templates = carpal tunnel syndrome.

Given that we were in the last days of our release, my brain was perhaps not at its most efficient. We use the MediaWiki Book extension, so that we (and our users) can create collections of pages that can be downloaded as PDF. To get a translation quote, I decided to create a massive PDF.

This was no easy task. I don’t recommend it, so I won’t explain the torture involved. Plus, the resultant PDF did not handle the shared text, so the word count was not accurate.

Getting the content out of the wiki – attempt #2

Eventually, once our release was out the door and my head cleared, I did some more reading and investigated MediaWiki’s XML export feature.

First, I used the MediaWiki special page “All Pages” to display a list of all of the pages in the Main namespace. This list is displayed in three columns over several screens, so I pasted all of the page names into an Excel spreadsheet. Then I created a single column of page titles. Next, I copied this list from Excel into the MediaWiki page Special:Export. This page requires only a straight list of page titles, one per line, without the surrounding double square brackets, so the copy-and-paste from Excel worked perfectly. I chose to include only the current revision, not the full history. I chose to include templates (shared text). And I chose to save to file.

To my great relief, the XML file was very readable, and shared text was included only once. The translator provided a second quote and said that they felt more confident with the XML file than with the earlier PDF.

So, we’d taken care of points 1 and 2: We got the material out of the wiki for a quote and translation, and ensured that shared content would be translated only once.

A medium for translated content

Now, what to do with the translated text? The only sane option would be to use MediaWiki’s XML import feature. To do this, we’d need to abandon our current model of having the Japanese pages alongside the English in the same wiki. Instead, we’d need a separate Japanese wiki, where we could simply import the translated XML file. Changing our translation model also means changing how the Japanese documentation is integrated into our software.

Documentation style

Last and most painful: how well does our documentation lend itself to translation? My research and common sense told me that we have some work to do. For example, to make our documentation more engaging and user-friendly, we’ve adopted a casual, conversational, and (some might say) humorous style. This can make translation tricky, but it can also be problematic for ESL readers. And what we think is funny here in Canada may make no sense, or may be just plain annoying, across the pond. I’ll write more about style issues and translation in a future post.

Documentation is the castor oil of programming. The managers know it must be good, because programmers hate it so much. Gerald M. Weinberg

I used to be a strong believer in formal doc reviews. Distribute a draft, plan a meeting, and have everyone gather around the table. But in the last few years, my team has moved towards mostly meetingless reviews–because people hate review meetings (you know, like code reviews, only worse), because people haven’t always read the drafts when they get to the meeting, and because some of our dev team is overseas.

• First, we distributed PDFs and asked reviewers to submit comments in email or on a hard copy. For the overseas team, email was the only option. This is not fun for either the reviewer, who has to do a lot of copying and pasting and referring to page numbers, or for the writer.
• Then we tried Adobe Acrobat PDF reviews, which allowed all reviewers to comment on the same PDF and view others’ comments. This was a big improvement over the email method.
• Now that all of our product documentation is hosted on a MediaWiki-based site, we’ve asked reviewers to edit the pages themselves, or add comments to the Talk pages. This makes life much easier for both reviewers and writers.

Still, as Anne Gentle stresses in Conversation and Community, using a collaborative medium doesn’t guarantee that collaboration will happen.

How do we encourage developers and testers to “own” the documentation for their tools, and to think of help as part of the product? If we can get developers and testers to RTFM, the benefits are obvious. They understand the tools in a way that no one else does, so they’ll provide feedback that no one else can. And they’ll become familiar with the help for the tools they’re responsible for, so they’d know whether a change they’re making or testing would affect the help.

I thought up a few ways that might increase the amount of review feedback:

• Create review tasks in our Agile project tracking tool, XPlanner. A top-down approach, and I wasn’t enthusiastic about it. Kinda like the daily castor oil treatment.
• Make everyone’s MediaWiki user page into their doc review page; we’d add links to these pages and reviewers would be notified through email, then they could delete the link when they’ve reviewed it. A nice bottom-up approach, I thought, in the spirit of the wiki.

But encouraging collaboration may be less about tools and more about process. If we involve reviewers earlier, they can tell us what they think before we’ve written a draft. A draft takes a long time to review, and if a reviewer doesn’t like it, they might not provide any feedback at all.

As Donna L. Davis says in a review of Andreas Rüping’s Agile Documentation:

Documentation isn’t bad. But bad documentation is terrible.

Is reviewing docs worse than eating Brussels sprouts? Do you review docs when asked, or do you hide the invitations under the edge of your plate, hoping mom won’t notice? Is the help so bad that you can’t be bothered? Are you just too busy? Are you one of those people who never consults the help for tools you use? Do you think your users will be able to use the tools you’re developing or testing without the docs?

What would make you more inclined to “own” the help for the tools you’re developing or testing?

The not-so-agile technical writer

I’m a technical writer who’s a big picture kind of person and that means agile development is sheer torture for me.

Going into my second agile project, I thought I would be able to go with the “flow” a bit more. I was wrong.

But, it’s important to point out that our documentation team hit all of our deadlines for new features, while substantially rewriting our help set and moving it to a wiki. I’m pleased with the outcome, but the trip was not pleasant.

This will be my first post in a series about technical writing in an agile environment. Today’s post outlines the obstacles that I face—aspects of being me (mostly). The next post will outline my coping mechanisms, as well as our team’s plan for our next project.

If there’s no follow-up post, that means that my unbridled honesty has gotten my keester kicked to the curb.

Waterfall nostalgia

I got started on this tech writing gig as a consultant. The product would be a month or two away from release, but mostly fleshed out and I’d swan in, grab the requirements documentation and the design specifications (sometimes I’d write those), play around with the tool and voilà: a manual. I could be very single minded about what I was writing and just get it done.

To be clear, I’m in no way saying that the waterfall method delivered better products or documentation, just that I had a better view of where we were going.

With agile, I feel like I’m jumping hither and yon doing all these minute tasks, with very little view of how they’re supposed to fit together. I’d often snarl to my manager after meetings that “I’m given a doorknob, a shingle and a shrub and told to go build a house with them.”

In fact, in his blog post about minimalist documentation and agile, Shannon Greywalker hits on my problem very accurately, and it’s this: “user stories are typically too granular” for minimalist documentation. Minimalist documentation, as he says, requires the “35,000 foot view”.

And what I want runs counter to the whole agile methodology: THE BIG PICTURE RIGHT NOW.

Multi-tasking versus uni-tasking

Another problem I face is that I’m a uni-tasker; I like to finish what I start—not doable when features span several development iterations and are in major flux.

There are blogs out there about what Generation Y is like, good or bad, but the one thing I do envy is their multi-tasking ability. These folks grew up doing homework, while downloading music and instant messaging their friends.

That’s the kind of splintered attention I envy. So, I got David Allen’s book, Getting Things Done, but I couldn’t finish it. I read the line about having “a mind like water” and then froze. Uh-oh. Mind like ice. When I think of my work and personal to-do lists, I’m paralyzed.

So, I signed up for meditation classes and I’m now making another attempt to read Getting Things Done. I’m hoping it’ll help me switch directions faster. Not easy when you feel like the Titanic and need an hour’s notice to hang left. Now that I think about it, the Titanic is a career-limiting metaphor.

Procrastination

Now it’s time for confession. Our documentation department fought for and won a two-week offset for our last two projects. Yep, that’s right, we trailed development by a two-week iteration.  It’s amazing that we haven’t been rounded up and thrown in agile jail.

By procrastinating this way, we hoped that features would be more fleshed out before we started writing about them. It was our vain hope that this would contain some of the rewriting efforts. We still did a lot of rewriting, but this round we were rewriting a lot of material for the wiki anyway, so the offset didn’t matter that much.

By now, you’re probably thinking that it must be very hard being me. Don’t cry for me, Costa Rica; I have ways of getting by. Tune in whenever the next post surfaces to find out how I cope and how I hope to improve.

Our new documentation wiki is up and running!

For awhile it seemed like we’d never do it. We have a team white board that records our panic level, and for several weeks, the level was up around “hysterical” and “wanting to open my own daycare”.

We also have a white board in front of the doc area, in a hallway where everyone walks by to get to the kitchen.  At one point when we were particularly frustrated with MediaWiki, the topic was “names for the new doc wiki”. A few good suggestions:

the gaping maw, or "the wiki is never done"

And the best one, though we decided it would be unprofessional to make it official:

RTFW

Fortunately, when I was ready to throw in the towel, our IT guy stepped into the ring and beat MediaWiki into submission. He installed extension after extension, found a search engine that worked for us, and configured a great PDF creator. He moved the entire Wiki a few times to improve performance and security. And he was much more tolerant of the state of MediaWiki’s documentation than I was.

So, if you’re a small documentation team thinking of moving to a Wiki, what do you need to make it work?

• Someone outside the doc team needs to handle the technical side, so you still have time to do what you do best: write user documentation. In our case, besides IT, one of our senior developers ended up learning more than he probably wanted to about MediaWiki. He made the wiki the source for context-sensitive help for detected issues; each of these wiki pages allows you to switch from English to Japanese. Some of our users have no access to the internet, so he also wrote a script that exports the wiki to static html for packaging with Klocwork software.
• Read blog entries like Tom Johnson’s Ramping Up on MediaWiki to remind you that you’re doing the right thing.
• When the voices in your head whisper that it’s impossible to both switch your help delivery mechanism and reorganize/rewrite the entire help system in just a few months, take a pill or something.
• When your inner perfectionist rears its ugly head, repeat this mantra: The wiki is never done. The wiki is never done.

In the end, despite feeling like we were being drawn kicking and screaming into the gaping maw of hell, we love our wiki, and we hope our users will too. And users, if you don’t like it, you can change it!

Going beyond "getting started"

“Now what?” is that uncharted territory between “Getting Started” product guides and the challenge of incorporating a new tool into day-to-day activities.

In fact, I’m convinced that “Now what?” is one of many creatures inferred by the “Here be monsters” legend inscribed on uncharted regions of old nautical maps.

I think of it like this: You buy an exciting adventure package to Costa Rica. You put your money down. The tour operator hands you a map. And then you end up…in Holland.

Time to call your emergency number:

You: “Can you help me out? I was supposed to go to Costa Rica and I followed the directions, but I’m in Holland.

Customer support: “Let’s go over what happened and take a look at the directions.”

Customer support reviews your actions and examines the map. (They are incredibly patient, discerning and resilient people, these customer support types.)

Customer support: “It appears that you took a wrong turn at Albuquerque (except it’s pronounced Albekoiky).”

Then you’re put on the right road. A problem report gets logged against the map-makers to clear up whatever ambiguity there was. Now you and future travelers can end up at the intended destination.

Excellent.

“Okay. I’m in Costa Rica. Now what?”

Exactly.

This is an issue sales engineers frequently encounter in the field. It is also something that Geoff Babb touched on in his response to Helen’s post, “Exposing our soft underbellies“,  about moving documentation to a wiki.

Useful examples are great, but finding the right scenario can be difficult, particularly when customers can range from a couple of guys in their basements to companies with thousands of developers.

With a large documentation set, it’s difficult to keep up with new features and include scenarios that are relevant to everyone—a major rewriting effort indeed.

During a meeting where we presented our documentation plan for moving to a wiki, “Now what?” showed up again.

I don’t remember putting “Now what?” on the list of invitees. But it appears that there’s no stopping that beast.

Our move to a wiki means rewriting a helluva lot of material anyway. Might as well take on the beast.