I came to the practice of procrastination late in life. I was always one of those annoying people who arrived for appointments early, handed in assignments early, went to bed early.

Becoming a full-time working parent drove me to the dark side.

Now I’m routinely late — late for exercise classes, late going to bed, late getting the kids to daycare.

My forgetfulness factor has increased about 26-fold too. I’ve always been a list-maker, but now I have a few sayings that my husband is sick of: If it’s not in my calendar, it’s not getting done. If it’s not on the grocery list, it’s not going to show up in the fridge.

My work equivalent: If it’s not in XPlanner, it’s not getting done.

However, I’ve also discovered that adding tasks to XPlanner is a necessary but not sufficient condition for something getting done. Ever so occasionally, I’ll realize that a task in my slightly overlong list of tasks for the iteration should have been done… yesterday.

In my pre-kid years (which incidentally and unfortunately coincided with the days of larger doc teams), that just didn’t happen. I had sufficient brain space to accommodate what needed to be done.

My colleague Patti and I decided to elevate this practice of procrastination in agile documentation by giving it a name:

DOCRAGINATION.

Fortunately, in my latest slip into docragination, I got away with it: I wasn’t the only reason for another software build.

As I get older, I’m growing more certain that procrastination in general is not always a bad thing. There’s something to be said for waiting, listening, processing — even sleeping on it — instead of rushing in and finishing.

Patti just reminded me of another of my annoying sayings: What doesn’t get documented today won’t have to be revised later.

After six years of post-secondary education, my first day of the real world had finally come.   As I approached the doors to Klocwork, I realized it was time to put all my years of education to the test.

Straight out of high school, I had little idea of what career path I should take. Four years of university passed and I graduated with a B.A. in English, but still, I didn’t feel prepared. Another two years of college in media-related studies and, ready or not, it was time to make the leap into the working world.

My first day could be described in exactly two words: a blur. Between getting set up at my desk and meetings with my superiors, it was easy to feel overwhelmed. Nevertheless, after I got past the initial nerves of starting a new job, I felt ready for whatever was to come my way.

As it was put in my very first meeting at the company, I would be given “a taste of everything”. A taste was exactly what I had needed to get myself started and get some experience under my belt.

Fast forward almost two months and the experience has been nothing short of a rollercoaster.

One of my most rewarding and yet most challenging experiences since I started here has been a project which consisted of redesigning part of the documentation wiki. One of my colleagues, Patti, has been in process of designing a new landing page, and I had been asked to carry her design over to the wiki. While the task might seem simple, it has been challenging.

When I first glanced at the page, it didn’t think there would be many issues. I’m not afraid to admit that I may have made a poor assumption.

One revision after another, I faced one obstacle after another. Problems ranged from something as simple as getting the correct spacing to more complex issues dealing with specific browsers. The end of the week was near and I felt as if I was getting nowhere.

I let myself walk away from it for the weekend and came in the following week with a refreshed mindset. While it was quickly becoming evident this particular design would not work, there was still light at the end of the tunnel. With some guidance from the documentation team, we quickly got back on track.

Now with the page’s design nearing completion with approval from the key players, it’s something I certainly feel proud of. It’s a prime example of how much I’ve learned in the short time I have been with Klocwork.

While I know work may not always be fun (a few repetitive tasks come to mind), at the end of the day, I think it is projects like this that make it all worthwhile.

In my next post, I’ll share some more of my experiences working with the support, documentation and training teams.

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?

When I was documenting a new refactoring plugin for Vim, I checked out the Vim web site, and came across this blasphemy:

Vim isn’t an editor designed to hold its users’ hands. It is a tool, the use of which must be learned.

Later, someone sent me this beauty, from Elitist Jerks:

Stop being lazy and read.

Are users lazy? Do they expect hand-holding? Do they expect one button and no manual?

Or is this more true to life?

In the end, it probably comes down to this: Make tools usable. Then technical communicators can spend more time creating truly helpful help, and less time explaining a bad UI.

If our goal as communicators is not just great help, but a great product, Agile makes more sense than ever.  If we want our usability suggestions to be implemented, we need to get developers’ attention while they’re working on that feature. Find the rough edges that would require a lot of splainy-splainy, request a change, and then rejoice that we don’t need to explain what’s now obvious. Sometimes it’s hard for me to decide what’s a rough edge. Would my audience of developers find this as confusing as I do? But I’m learning to trust my gut.

At the same time, though I appreciate the benefits of Agile, I’ve started to worry less about the help being “done” at the end of an iteration; instead, I want to make sure I understand a feature well enough before the end of the iteration to suggest design changes and know what help will be required.

Spend 80% of your time on One Thing.

As a manager of a small tech writing team in an agile environment (are there any large tech writing teams left out there?), it’s easy to lose myself in how-the-heck-can-we-keep-up-with-myriad-coders-frantically-coding thinking.

So when my manager scheduled a meeting to ask what innovations my team has planned for the next release or two, I thought of a few choice responses, such as “Um… how about documenting the new features in time for release? Is that innovative enough for ya?” and “Innovate THIS.”

Eventually I calmed down, since he’s the boss, and I have a mortgage.

I looked at the presentation I’d given after our last research period, that oh-so-short breathing time between releases. I reviewed the precious feedback we’ve gotten from a few customers and thought hard about it. I felt a bit better when I realized several of the goals we’d set for ourselves were already underway.

I dutifully wrote up a wiki page (because I can’t think without writing) that summarized a bunch of initiatives under each of our themes: process, community, quality, coverage, usability, and media. And I decided whether they’d fit into this release or the next. And I sent it off to my manager before our meeting.

He said OK, but where does all this get us?

He called my list depressing. Death by a thousand cuts.

He told me that to be successful, you need to put 80% of your time or money into one thing.

He suggested creating completely different help for just one tool. Throw out the old stuff and start over.

Once I played devil’s advocate for awhile, I began to see where he was going with this. I suggested a tool that I thought would be a good candidate. So I think we’ve picked our One Thing for this release.

Here’s how I’m thinking about our One Thing so far:

• Make sure everything the user needs to know is accessible from one place.
• Target two very different points of interacting with the help: the getting started phase and the troubleshooting phase.
• Use media that are best suited to the user and the information that needs to be conveyed.
• Make the help interesting, fun and effective. Grab and keep the user’s attention long enough to convey what needs to be understood. Defuse frustration.

And again (annoyingly), my manager is right; it’s much less daunting to try to make one thing better than to try to make everything better.

Now to persuade a few of the developers to star in our walk-through video….

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!

I remember that idyllic summer day when I saw my very agile dog Maggie jumping through the sprinkler. I laughed until I cried. And then I thought:  This reminds me of what I do for a living.

Jumping into the Agile fray: a technical writer's perspective

I’m a technical writer and technical writing in an Agile environment is somewhat like chasing those water drops.

You can run after those features, but early in the game there’s not really anything to hold onto.

So, how does one document a feature that will probably change from one iteration (or day) to another without chasing one’s tail?

Workflow can be your rock in that ever-changing environment. While the feature is likely far from finalized, someone’s gotta have an idea of how people are going to interact with it.

The developers can get you started, but the workflow people (at least in my experience) are the product managers.

So, while my agile dog chases water drops, this technical writer chases product managers—and if I still don’t have enough of a big picture outline for the feature or a collection of features, then the Chief Technical Officer is in my sights.

For major features “in flux”, the best way to get “good enough” content to meet your iterative deadlines is to channel the Australian shepherd within and herd the developer, product managers and testers into a room with a whiteboard and a marker.

In half an hour, you’ll get something workable. And maybe a chance to put your two-cents’ worth into the design.

What if there’s no workflow available?

If it’s a sunny day, go find a sprinkler to jump through. These days, that’s a chilly prospect indeed.