I'd Rather Be Writing » IT Author

Breaking Things as a Form of Creativity

Tom Johnson — Thu, 01 Jul 2010 14:26:30 +0000

IT Author’s latest podcast, Testing testing 123, dives into testing. Rather than just commenting on testing from a technical writer’s point of view, Alistair Christie and his co-host Graham Campbell interviewed an actual tester. It’s a good interview with lots of informational nuggets. For example, “regression testing” is testing those software features that were tested previously. Every new feature has the potential to affect other features, so even if you’ve already tested something, you have to test it again.

While listening to the show, I admit I felt a sense of gratitude for not being a tester, because they seem to lead somewhat dull lives. But later in the show, the tester, Richard Paterson, explained that breaking things requires a lot of creativity. It’s not just a matter of ensuring things work, but thinking about non-standard ways that customers might use the product to break it.

There is creativity in destruction.

Testing also invites you to figure out how something works, so it requires a driving curiosity about how all the parts fit together and interact on a deeper level. By the end of the show, I began to see how testing could be an interesting, fulfilling job.

Prescription and Description

Apart from creativity and curiosity, during their discussions about testing, they also noted that testers look at whether the product works according to the design specifications, whereas technical authors look at how the product works as implemented in a development environment. In other words, testers look at the product from a prescriptive point of view. Technical authors usually look at the product from a descriptive point of view.

I find this fascinating and true. In our agile environment, our design specifications are thin and rely more on the interaction designer’s prototypes, discussions in meetings, and one-on-one’s with the product managers and team leads. Sometimes the implementation changes from the prototypes, so it’s hard to refer back to any design specification as a standard. Additionally, the prototypes, once created, are not always updated to reflect the latest changes.

Because we so often work descriptively, we feel that we can’t start documenting a product until we have an environment to explore. But recently a friend of mine told me an interesting story. She said she once tried writing documentation based on the specifications rather than the product (which hadn’t been coded yet). She poured through the specifications with such thoroughness that her meetings with the product managers and other team leads would drag on for hours, as she clarified the absent detail and other gaps in the specifications. After a while, the product managers recognized her thoroughness and insight and made her a product manager.

So while we often don’t write prescriptively, according to design and functionality specifications, there might be advantages in doing so. As a counter to this point, Graham noted that there’s a danger in getting involved in the project too early, because as the product changes, the documentation you wrote early on gets outdated. You end up rewriting everything.

Test Cases Versus User Documentation

Another interesting discussion in the podcast included parallels between test cases and user documentation. Presumably, the tester has written test cases that list the steps for all major functionality in the application. User documentation lists the steps for tasks the users want to complete. Can’t we borrow or at least drive some of our documentation from test cases?

I think test cases can be helpful, but they can also be harmful. Helpful because they give you a starting point about what to document. Harmful because a tester’s perspective is not the same as a user’s perspective, and as I mentioned in a preceding post, our documentation should focus on the problems and issues users will have, rather than just describing the basics of an application.

Different Perspectives

Overall, the tester on any project team is a person you need to know well. I find that in my organization, testers know the product inside and out, and they’re less busy than project managers in answering questions.

At the same time, while most testers are analytical and sharp-minded, they focus too much on this question: Does the product work as designed? Technical writers, as user experience champions, have another question in mind: Is this design working?

Blog Sponsors

Generations Change, But Help Formats Remain the Same?

Tom Johnson — Tue, 09 Dec 2008 13:45:37 +0000

Today should have been a day of great excitement, almost like a coronation. Having struggled with a 175 page user manual for several months, I finally finished a first draft. Today I met with the client, alongside the senior project manager, the project manager, and a few others to present the sacred document, with the words “Reference Manual” on the front.

I say it should have been a day of celebration. Instead, it was an event I knew was out of date. The client flipped through the manual, glancing. He then set it down and we talked about reviewing schedules, because no one felt the client would actually read the manual on his own. Yes, we had to nail down a schedule and force him to choke it down in weekly bites.

In truth, I dislike delivering “the manual.”

In “Move over DITA – Chaos Is Coming!,” Alan Porter suggests that rigid structural writing, such as DITA, is at odds with the looser, more chaotic social media so prevalent among the younger generation. Rather than trying to force-fit the DITA standard onto our documentation, he says we might instead “step back and look at how [our] kids do their homework. Because in five to ten years they will be [our] new workforce, and perhaps more importantly, [our] new customers.”

In other words, we should rethink our documentation model. Rather than a rigid structure, we might consider following the pattern of how people actually access and use information today.

Exactly how do kids do homework these days? Alan says his daughter uses a variety of social media applications — wikis, social networks, instant messenger, folksonomies, social bookmarking. Observing his daughter complete her homework, he writes,

The first thing she did was google “Pearl Harbor” and started visiting links. First stop was Wikipedia. Then she got on Facebook and YahooIM and started using messaging to ask friends who were online for recommendations. These friends were literally from all around the world, so she was given access to resources that gave totally different perspectives than those given in the classroom. …One friend suggested going to a social bookmarking site and searching using a variety of user applied tags. Instead of taxonomy she was now applying folksonomy.

In a recent IT Author podcast, Alistair Christie interviews his daughter about how she uses computers, and his daughter explains that she never uses the help, because it’s almost impossible to find what you’re looking for. Instead she learns by simply using the interface, clicking buttons, looking at labels, and asking others for help if she needs it. The world of traditional help deliverables — long manuals with table of contents and indexes, expandable books in online help, even video tutorials — these all seem last resorts in user’s mind.

I don’t use the DITA model, but I do use standard topic-based authoring methodology, single-sourcing between online help and a printed PDF. Reading Alan’s post and listening to Alistair’s podcast, as well as hearing the feedback I always hear about help –- “I try to learn the application on my own first, and only turn to the help when I’m stuck” –- makes me think the old-school paradigms of help (the manual and the online help) are falling by the wayside. They aren’t harnessing the latest social media technologies. They aren’t appealing formats.

Alan also observes a sad truth:

For most of my working life to date, the technology I used at work far outpaced that I used outside of work.

But not any more.

Now the technology I use at home has generally outpaced that found in most workplaces.

This is the tragedy of technical communication. Rather than embracing and leveraging the latest web technologies, tech comm is stuck in the early 1990′s, delivering the same old content that no one wants and few can make sense of.

Blog Sponsors

IT Author Podcast — Two Podcasts on Flare, One on the Making of a Technical Writer, and a Dogcast on User Psychology

Tom Johnson — Mon, 12 Nov 2007 06:11:04 +0000

I listened to Alistair Christie’s IT Author podcast the other day online and then later driving home from work. Alistair is based in Scotland and has one of the most enjoyable podcasts on technical communication around. If you listen to podcasts, add his podcast to your feed. His latest episodes are as follows:

In Flare: the good stuff, he explains the features of Flare that he really enjoys, such as being able to integrate his own javascript and PHP scripts directly into the code.
In Why do we use Flare?, he and a colleague talk about Flare in depth — for about an hour, actually, discussing the little things that annoy them about Flare, such as the visual editor.
In What does it take to be a technical writer (a carcast), he mentions some key qualities technical writers need, such as a curiosity for learning and understanding how things work.
In his May 19th Dogcast, he actually gives the podcast while walking his dog. The podcast covers the evolution of help, the need for technical communication, and user psychology.

Although the dogcast started out slow, this was the podcast I enjoyed the most. About 15 minutes into the podcast, he really hit his rhythm and started driving down into the topic that seemed to grip him most: user psychology. Users don’t read manuals. The days where long, printed manuals were standard prerequisites to using technology are gone. People experiment with an application and try to learn by doing; when they need information, they search for information about the task they’re trying to accomplish in that instant. Online help is critical in helping users find a single piece of instruction for an immediate need.

Users are also in a state of anger and impatience when they turn to the help. They’re mad because the software has frustrated them and stopped their work. They don’t want to read a manual. What they really want is someone to explain to them how to do something.

Listening to Alistair’s thoughts on the user’s state of mind made me think about the help we write. Why is it that we often begin a software documentation project by documenting all the tasks that users can possibly do from all the available functions of the software application? We spend the bulk off our time creating written instructions that almost no one wants or reads.

Instead, I think we should be focusing on several key deliverables:

Audiovisual tutorials or screencasts
Short getting started guides covering the basics
Context-sensitive online help

Further, we should begin by getting to know our user — not through a description from the SME or business analyst, but actually contacting the user to determine the tasks they want to accomplish and the format for the help.

The Getting Started guide should walk them through the most common, basic tasks the user will need to perform. This guide should be easy to get through. Alistair says the help should provide immediate rewards to the user. Take them through some quick wins. In the Getting Started guide, you give them easy-to-perform tasks that make them successful.

The screencasts (which should also be short) provide a range of other benefits, such as providing the experience of a friend showing them how to use the application.

The context-sensitive online help gives the user immediate information about the task at hand. The online help also provides a searchable database for answers.

So often we begin with the comprehensive manual in mind, when that’s the last priority for users.

Additional Resources

A few months ago I posted some notes from a Kathy Sierra presentation that talked about the user’s state of mind as well.