I'd Rather Be Writing » story

Using JIRA to Track Writing Assignments

Tom Johnson — Wed, 18 Jan 2012 14:57:28 +0000

We had a couple of writing interns join our group this month. To track writing assignments for the technology blog, I’ve been using JIRA. JIRA is a bug tracking tool from Atlassian (the same company that makes Confluence). It’s typically used by software teams to track bugs during software development projects. You can add comments to items, assign items to team members, assign the items to sprints, create advanced viewing filters for the items, and more.

Since I’m using JIRA to track writing assignments, I have to live with a few compromises in terminology, but so far I like the system. Here are some details of how I’m using it.

Each item in JIRA is an article. I add only articles that we’re really going to write. (For general ideas that may one day be something we write, I put the ideas elsewhere.)

I assign the JIRA items to the writers who will write the article. If there is no writer, I leave the article unassigned.

I give each article a story point weight of about 10 points. Another section of JIRA allows me to define specific sprint release windows, and I organize sprints (based on weeks) to accept no more than 70 story points. This means that each sprint can only have 7 articles, assuming each article is 10 story points. However, I can also adjust the story points for each article. For example, short articles might be 3 story points, while longer articles might be 15 story points. Adjusting for the appropriate number of story points helps us avoid over-allocating work for the week.

In the JIRA item, I try to outline the general ideas the article should cover. I also add comments about each item, and the assignee receives an email notification with each comment and edit.

When an article is completely finished and published, I change its status to Resolved. Or if we decide to not do the article, I resolve or delete the article. The resolution statuses include Fixed, Will Not Fix, Duplicate, and some others.

I can assign different priorities to the articles — 1, 2, 3, 4, or 5. A priority 1 is called a “blocker.” Priority 2 is called “critical.” Priority 3 is “major,” and so on. (Here’s where the terminology doesn’t quite fit for writing assignments.)

JIRA’s filters are robust, but I am using them in a simple manner. I create a filter to show all items assigned to each intern, and then I save those filters as bookmarks. When I review and plan articles with the writers, we just select the JIRA filter and go down the list of what they’re working on.

I’ve tried various ways to organize and track writing assignments, and so far this one seems to work well. Of course no system works if you don’t actually use the system, and no system is perfect. I used to have little slips of paper pinned all around my cube. I’ve also tried Excel spreadsheets, as well as SharePoint.

But using JIRA to track writing assignments is particularly beneficial because familiarity with JIRA helps out with our involvement in project teams. In our IT department, many project teams use JIRA, and familiarity with JIRA makes it much easier to stay abreast of project news, releases, bugs, issues, and other details. Often the lifeblood of a software project is captured in JIRA, since this asynchronous sharing of information helps everyone on the team remain aware of what’s going on.

One thing I’m not using JIRA for is to manage the actual documents. While I could upload file attachments, I find that Dropbox is much easier. Dropbox is almost like a net file share drive. I could spend an entirely separate post describing how much I love Dropbox, but so that I stay on track, I’ll just say that I try to name the Dropbox folders the same as the JIRA item titles.

One other shortcoming of JIRA is that it doesn’t allow me to change the statuses of items in a customizable way (at least I haven’t figure out how to do it yet). I’d like to indicate various states of the article as they pass through the approval processes, but alas, the issues in JIRA are either Open, In Progress, or Resolved. (Perhaps it’s best to keep it simple.)

I’d be interested to hear what system you use to manage and track writing assignments.

Blog Sponsors

Visual Storytelling Guides: A New Deliverable in Technical Communication?

Tom Johnson — Wed, 12 Oct 2011 14:02:22 +0000

When I read books to my little girls (ages 5 and 7), the pictures combined with story provide a captivating experience. I’ve often thought that if I wanted to create documentation that people actually read, maybe I should integrate these two same elements: picture and story.

I’m not entirely sure what a product would look like that integrates these two elements, because technical writing usually lacks both visuals and story. It usually consists of dry technical procedures written in a list, meant to be read in any order, and stripped down to its most minimalistic expression.

So perhaps what I’m envisioning is a different kind of deliverable, rather than a remake of an existing deliverable. I’ve grown accustomed to creating the following standard deliverables:

Webhelp (HTML)
How-to Guide (PDF)
Quick Reference Guide (PDF)
Video Tutorial (flash)

Now there’s one more to add to this list: visual storytelling guide. This guide doesn’t compete with the other standards we maintain. We still write the traditional online help file. We still create quick reference guides and videos. But with the visual storytelling guide, we let our hair down a bit more and not worry so much about the economy of information as we unravel story after story coupled with strong images and possibly video.

The visual story begins with a character. In most cases, you would create a user persona based on user research. You then give this user/character a name and context. Then give the character a problem (a scenario). The character would then attempt to solve the problem, and in so doing, the reader learns how to perform various tasks.

Harry Miller is probably the best example of someone who is already doing visual storytelling. His visual stories about using Microsoft Outlook replace the dry documentation that people otherwise might not read. Check out this series of video storytelling episodes complete with actors, scenes, and dialogue.

See the difference? Visual storytelling is a new kind of deliverable.

Blog Sponsors

Book Review: A Practical Guide to Designing with Data, by Brian Suda

Tom Johnson — Tue, 16 Aug 2011 13:10:21 +0000

A Practical Guide to Designing with Data, by Brian Suda

A Practical Guide to Designing with Data (Five Simple Steps, 2010), by Brian Suda, is a thorough exploration of best practices for graphs and charts. It’s somewhat similar to Edward Tufte’s Visualizing Information in focus, and both have a shared antipathy toward “chart junk” in the effort to tell the story of data. Suda explains,

The main purpose of this book is to encourage you to visualize and design for data in such a way that it engages the reader and tells a story rather than just being flashy, cluttered and confusing. (viii)

Everything that’s flashy, superfluous, and unnecessary is essentially chart junk. Chart junk gets in the way of the purpose in using a chart or graph, which is to tell the story of data. Any time you add visuals that distract from the data, or which don’t add to the data, this chart junk just gets in the way.

With this assumption, the graphs and charts Suda focuses on in Designing with Data are minimalistic. He encourages you to avoid bringing in too many dark lines or colors. To de-emphasize certain lines, make them light gray. To highlight an area, add a splash of color — but only a splash. Suda dislikes the gaudy multi-dimensional, multi-colored charts and graphs that you can too easily produce with PowerPoint, Excel, and other tools. He feels this excess of pixels all too often prevents the reader from understanding the data.

In a culture of visualization and infographics, Suda’s book is a wake-up call to graphic minimalism. Suda writes,

A visualization … seems to contain much more ‘chart junk’, with many sometimes complex graphs or several layers of charts and graphs. A visualization seems to be the super-set for all sorts of data-driven design. (11)

The focus on minimalism also has echoes in Jean-Luc Duomont’s Trees, maps, and theorems, which I reviewed last year.

Given the rising trend of infographics, Suda’s book provides an interesting counter. At Podcamp 2011, Tristan Higbee of Blogging Bookshelf said some of his most popular posts are ones with infographics; he now actually has a course on infographics. Higbee notes that people searching for infographics (see Google Trends for the term) has skyrocketed in the past few years. Most notable among the producers of infographics is New York Times. Check out the New York Times’ gallery of infographics. Fast Company also has a category dedicated to infographics.

Given this trend toward infographics and visualization, it’s easy to get caught up in the graphic design of the information, emphasizing the artistic aspect of the display. Yet Suda says,

To tell the story behind the data, we need to stop grasping for the perfect visualization and instead return to the basic language of charts and graphics. Only then can we begin to uncover the meaning and relationships the data has to offer. (v)

Returning to the basic language of charts and graphs is the core theme of the book. The debate between minimalism (with basic graphs and charts) and decoration (through infographics and other visualizations) is something Suda touches on with more depth outside his book, in a comment on a 10 minute BBC video clip about “making information beautiful.”

Two artists have contrasting views. David McCandless wants to bring his graphic design skills to the information landscape to portray information as a kind of art, to evoke more than mere information but also patterns and emotion and attention. Neville Brody says that over-visualization can too easily become pretty “wallpaper” — something that’s pleasing to look at, but which misses the underlying point of the story. The story gets lost in the decoration.

Suda comments:

While I personally find myself agreeing with Neville Brody, I also find myself defending David McCandless. Neville’s flippant comment about “It is very pretty, I would like that on my wall”, goes to the heart of the problem with visualizations and infographics, they are decoration more than they are tools to convey data. (The art of making information beautiful)

Although he sides with Brody, he applauds McCandless for pushing the limits and compares him to information pioneers such as Florence Nightengale, whose innovation in displaying information led to the formation of a new type of chart.

Designing with Data provides excellent information if you’re designing charts or graphs. If you’re looking for a book that explores infographics and visual storytelling, this book isn’t it. Yet Suda’s book still provides a good reminder to avoid unnecessary elements and decoration that distract from your story. In the last section of the book, Suda notes that he’s not opposed to more elaborate visualizations. He just encourages readers to first master the basics and tell the story, and then to experiment with something more artistic or creative after that.

Blog Sponsors

Where Topic-Based Authoring Fails: End-to-End Scenarios

Tom Johnson — Wed, 25 May 2011 14:19:51 +0000

After my Summit presentation about breaking out of topic-based hierarchies, a lady named Ursula came up to me and said she was tired of topic-based authoring. I asked her what the alternative was. She said she’s often more interested in seeing an end-to-end process rather than a specific task. This reminded me of a tutorial on Lynda.com in which Deke McClelland, the trainer, showed how to make a black cat, with the eyes, curly whiskers, gradients, and all. The process involved probably 10 different tasks.

This tutorial walks explains how to make this black cat. It relies on about 10 different techniques used together. (The full tutorial is at Lynda.com, which requires a subscription to access.)

Ursula has a good point. The problem with topic-based authoring is that many times these tasks don’t mean a whole lot in isolation. Like drawing a cat in Illustrator, you have to rely on a number of different tools and techniques working in combination, sequence, and tandem. You could separate out all of these tasks out from the whole, but when you do, it’s hard for the user to see how the tasks are used in combination with each other.

This kind of organization might be labeled end-to-end scenario organization. The problem is that the specific scenario may or may not apply to the user. With the example I mentioned, it’s great if you’re drawing a cat. But what if you’re drawing an elephant, or a human? Surely some of the techniques may apply, but users may not realize it while scanning topic titles.

Traditionally we teach people individual skills and tools and then let them apply them in different sequences and combinations for their particular task. The problem with this topic-based organization is that it doesn’t teach you how to use the tools in combination with each other.

Showing an end-to-end scenario can’t really be solved with the metadata and query method that I explored earlier. To summarize, my direction so far has been to chunk help material into small pieces, attach metadata to each piece of information, and then sort it based on different metadata queries. But all that method really does is return a bunch of lists. Those lists may not be that helpful to your users. What they may find more useful is a topic that shows an end-to-end scenario, which is not something you can feasibly show through any kind of automated process.

Other types of organization also fall short with the metadata queries. A cousin to the end-to-end scenario is the story/workflow-based organization. Describe a typical workflow scenario for a particular role, linking to each topic as it appears in your story. No automated retrieval process can pull results together into a story, yet this format might speak in a more real way to the user.

Another organization that doesn’t really work well with metadata is a level-based documentation. Think of karate levels, where participants master a specific skill and then move up to the next level. I mentioned an earlier example of this from Kathy Sierra and her Pirelli horse manuals. As a user masters one set of tasks, you push that user up to the next level. This level-based documentation is much more sequential in a beginner-t0-advanced way. It builds on certain skills and allows the user to advance to the next level after achieving competence at one level. It’s hard to imagine this system achieved in an automated way. Yet this type of organization might be much more helpful to users.

Overall, I think I may have overemphasized the usefulness of metadata in sorting information. In a presentation at Confab, Steve Rosembaum warned about the inability of computers to curate content in useful ways. He says that computers just don’t do well at collecting, organizing, and contextualizing content. You need a human being to do it. I think he’s right. Some of these more useful and interesting forms of content curation are only possible through a manual, thoughtful process.

That said, there’s no reason why you couldn’t do both, providing queries based on metadata as well as arranging the content in custom ways.

Blog Sponsors

My Brand Is …

Tom Johnson — Thu, 18 Nov 2010 08:14:03 +0000

I’ve been thinking lately about my brand. I’ve always hated this marketing term, but the word “brand” does help answer a question. When you think of me, what comes to your mind?

I’ve written about a lot of different topics on this blog, everything from findability to podcasting, blogging, technical writing, flare, wikis, screencasts, project managers, content organization, and more.

My content is diverse enough that when people ask me to speak at conferences or chapter events, they sometimes aren’t sure what topic I should cover. Maybe this broad focus dilutes my brand. At the Dallas Summit, for example, one organizer told me that when I submitted to speak about my topic, the committee didn’t feel I had a well-known expertise in it, but they trusted me anyway. And I came through.

Some people have established their brand in a strong way. Here are a few that come to mind: Anne Gentle is an expert in wikis. Sarah O’Keefe is an expert in XML. Ellis Pratt is an expert in marketing. Scott Abel is an expert in content management. Rahel Bailie is an expert in content strategy. Alan Porter is an expert in corporate wikis. RJ Jacquez is an expert in Adobe. Jack Molisani is an expert in business strategies. Ann Rockley is an expert in enterprise content. Neil Perlin is an expert in online help. Stewart Mader is an expert on starting wikis in organizations. And so on.

Most of the people I named are consultants specializing in these niches. But what if you don’t have that background? How can you build an online identity that brands you as an expert?

Here’s one strategy. To brand yourself as an expert, write about the topic you want to show expertise in. Even if you don’t know much about it, people will soon think or feel that you do. Either way, by pushing out post after post on the topic, you’ll soon be associated with the topic by default, regardless of your expertise. It’s kind of like those marketing surveys where they ask you what brand comes to mind when you think of cars.

That said, I want to refocus my brand. What I do most of all on this blog is … blog. I like to think of this as writing, but since everyone in tech comm is by default an expert writer, this strength isn’t a selling point. Additionally, a person blogs/writes about a specific topic (except for blogs about blogs, which I think miss the point.)

I guess I find myself leaning towards “new media.” But I’m not entirely sure what new media means, and in many ways my strength is the opposite of new media — I enjoy writing, which isn’t new. Is new media the only bucket that holds blogs, wikis, screencasts, wordpress, web-based help, web 2.0, user-generated content, and more?

I’ve written a few posts on content strategy, but I come across as abrasive towards this subject. For the record, it’s content strategy for tech comm that I raised objections to, not content strategy for the web. The latter I agree with, the former any good technical writer should already do, to an extent.

I do like content, but who doesn’t, and what does that mean anyway? For me, it means I like ideas, and substance, and eye-brow raising arguments. I like an interesting opinion, or an intriguing exploration of a topic. I like articulate thoughts in a well-structured form. Not only do I like content, I am also a content creator. But what kind of person specializes in content itself?

I also enjoy innovation. Conventions and status quo never sit well with me. I like to push new forms and try new techniques. I explore different paths. A colleague once told me that I’m an innovator – I create new sites, post about new ideas, and experiment with new strategies. But again, is innovation really something one specializes in? Maybe Scott Berkun, who makes a living off of this topic, can specialize in innovation. But sooner or later that topic catches up to you.

I also like to share personal experiences in transparent ways. These experiences are often the substance of my writing. But they’re a bit navel-gazing. When I find myself focusing too inward, I think of this quote from Jorge Luis Borges:

Through the years, a man peoples a space with images of provinces, kingdoms, mountains, bays, ships, islands, fishes, rooms, tools, stars, horses and people. Shortly before his death, he discovers that the patient labyrinth of lines traces the image of his own face.

I also like story — the raw, yearning narrator essaying against a conflict or idea at all odds and costs. Just when the conflict seems insurmountable, the narrator finds a new perspective that leads to a transformation and resolution. Stories drive meaning and engagement. Stories connect people to each other. Did you know I’m telling a story right now? It’s my struggle to define my brand. Transformation is coming, just hold on.

I know WordPress well — or well enough to pass as a WordPress consultant, anyway. But tool branding is pigeonholing. I know someone who feels trapped by his branding for Flare expertise. Once you’re branded with a certain tool, it’s hard to break free of it. What I like about WordPress isn’t the tool or technology itself, but the capability it provides to publish and design content.

I’m also a contrarian, but I don’t want to go down that path again. Psychologically, it’s probably indicative of a deep inner disturbance. Those doors are best left shut.

There are a few more sides of me you rarely see. I rarely write about those topics, because I like to maintain some privacy in my life. But sometimes I do write about them, and it feels good to be free to wander off my usual paths once in a while.

I am glad I am not bound into such a narrow niche as a brand. Maybe my brand is to resist brands?

In the end, though, my brand is probably writing. I’d rather be writing. But there’s a lot of latitude in that. The space is as wide as a desert landscape, with a lot of space to move around and explore.

I choose these goblin landscape things in the background as my brand. They go on for miles and offer countless paths and maze-like channels. This is Goblin Valley in southern Utah, by the way.

Blog Sponsors

Podcast: Finding and Creating Relevant Content — Strategies for Social Media

Tom Johnson — Fri, 08 Oct 2010 06:21:18 +0000

Download MP3
Length: 70 min.

In the barrage of information created by all the social media channels, how can you find relevant content? How can you move past forms of noise to actually produce content that engages users? What forms of social media do students respond to the most? These are some of the questions we explored in a presentation I gave to Brigham Young University Provo students earlier this week. This podcast is a recording of the presentation.

The podcast is about an hour long, and I bookended the presentation with some thoughts before and after.

Blog Sponsors

Replaceability

Tom Johnson — Mon, 19 Jul 2010 14:32:11 +0000

About a month ago, I was talking with some of my friends at church when my wife Jane came into the room crying and asking where Kevin was. I wasn’t sure what happened, but I soon found out.

Jane had been substituting in Primary, a class for children. During a game where everyone gets to ask a question, she asked if anyone had seen our cat, who had been missing for two days. All the kids became quiet. Apparently they all knew about a dead cat along the side of the road near Friday Station, the next community up from ours. One of the kids’ dads, Kevin, knew the details and location. So Jane made her way toward Kevin with more questions.

Kevin confirmed that it was an orange cat with a white belly. It had been hit along the parkway and someone scooped it off onto the shoulder. But when I drove to the area to look for the cat (Skippy), with a shovel and garbage bag in my backseat, I couldn’t find him.

I walked all over Friday Station in my tie and sunglasses looking for the cat, hoping to find him so we could bury him. I walked on the north side of the road, near the grass like Kevin had said. I knew my children would be waiting for news at home. I walked on the south side and in the grassy meridian and circled the cul de sac. I walked up the sidewalk, the same place I had walked before to see if I had somehow missed him. There was no sign, no bloody spot on the road, no skid marks. I looked carefully along the shoulder dirt to see if someone had buried him. Nothing.

Jane had given me the cat on my birthday. For the past ten years I’d half-joked about getting a cat or dog, but she was always opposed to it. I’m not sure why I wanted a pet. It seems so childish. But she finally did get me a little orange and white cat, despite all her objections.

We watched it grow from a kitten, where it would struggle just to go up and down stairs, to nearly full-cat size, with the ability to jump up a six foot fence, walk nimbly on top, and then leap off to the other side into the unknown.

Spot carrying Skippy in the snow

The cat had a biting problem, and continued to occasionally bite our two youngest children (despite our squirt bottle technique). As an attempt to mellow him out, we had him neutered. We also sent him outside more to help him get his energy out.

When Skippy matured, he started spending his nights prowling the town. He would go out at about 8 pm and come back at 5 am, waking me up with meows. He did rid our house and garden of mice, which is partly why Jane got him.

I suppose cats lives are short, though Skippy didn’t quite make it to one year. The cat always liked Jane more than me. She was his mother and she accepted him as a member of our family. Jane teased me that the cat was my only son, because our household is decidedly female, with three daughters and one more princess on the way.

After about a week of losing Skippy, I talked about possibly getting another cat. Jane felt this was sacrilege. “If I die, would you marry someone else within a week?”

I wasn’t sure how long we needed to mourn a dead cat. Maybe 2 months or so? Jane was also due next month, so now wasn’t the best time to get a cat.

We all felt a bit empty inside, especially driving past the place where Skippy was hit. Having not seen his body, I was left to imagine the car screeching, Skippy’s head getting crushed. Or Skippy limping off the side of the road and bleeding out. Not a pleasant thought.

Vole Holes

One day Jane noticed some mouse holes near the edge of her garden. They’re actually called “voles” where we live. Voles are faster, smaller mice that burrow all over your yard — and eat your garden vegetables. To get rid of the voles in her garden, she bought some rat poison at the store and asked me to dump it down the vole holes on the edges of her garden.

Jane is 8 months pregnant and eats routinely from her garden. There was no way I was going to put poison in her garden, despite the advice an older gardener might have given her. Jane wouldn’t open the poison herself, so without my willingness to do it, she didn’t have a whole lot of options. The poison remained in our garage.

I saw another mouse that week and told Jane. Jane loves her garden. I told her a cat could get rid of the mice. She indifferently agreed to another cat, but she insisted that the cat be strictly an outdoor cat and a champion mouser.

It’s hard to find a strictly outdoor cat. I called around, but the local Humane Society said all their cats were indoor cats (I still find this fact odd). I checked the classifieds, but driving out to different locations seemed like such a hassle. I queried for “mouser” or just “mouse” — not much came up. I guess all cats are pretty good mousers, so there’s not much point in stating it. Every owner touted that its cat was both a great indoor and outdoor cat. Probably trying to appease both requirements.

The Humane Society referred me to our local animal shelter, and last Saturday on a whim, feeling the need to get out of the house (because we all had just gotten over the flu), we drove down to check it out.

Introducing Amelia

To enter either kennel areas at the animal shelter, you have to step on a wet rag to sanitize your feet on the way in and out. The smell inside the cat and dog kennels is overpoweringly pungent.

Of the 20 cats on display, only 5 were fixed. (If a cat isn’t fixed, you have to pay an extra $50 to get the cat fixed.) Of those 5 fixed cats, one had bug eyes, three were old, and one was too young. The shelter workers didn’t know the history of any of their cats, since they were mostly strays. Whether a cat was indoor or outdoor, mouser or not, they had no idea. Interestingly, three of the kittens were orange and white, just like Skippy. They meowed exactly like him too. Even more coincidental, one of the orange kittens was actually named Skippy. But we weren’t getting another kitten.

I asked the clerks how frequently they brought in new cats. One of the clerks said each week they receive 60 to 80 new cats. Sometimes owners come and pick them up, but most of the cats are strays. When they’re first brought in, the cats are kept in a holding bay for five days of monitoring. If a cat is mean or wild or diseased or has other problems that make it unsuitable for adoption, it doesn’t pass the first test. The cats who do pass the test are promoted to the kennels, where they stay for one week. If by Tuesday the cats aren’t adopted, they’re put down.

Wow, what a piece of information to know. I could return next week, and all the cats I didn’t choose would most likely be euthanized. Those three orange and white kittens, just like Skippy? They probably wouldn’t make it past Tuesday before 60 to 80 new cats arrived, eager for adoption rather than death.

Unfortunately, I didn’t like any of the cats. I realize that my rejecting them means they would be furnaced (or however cats are put down), but I guess that’s how the system works.

As we were about to leave, a young couple came toward the shelter carrying a calico cat. The lady had red eyes from crying. The young man said, “We’re here to drop off a cat.” My three kids and I wandered over to check out the cat. The cat had light green, alert eyes and looked curiously around at all the other cats in the kennels.

“She’s a hunter,” the lady said. “She’s strictly an outdoor cat.”

My kids were going nuts hearing this. Jane, sitting in the corner reading a magazine, hid the magazine over her face and started laughing because she knew exactly where this was going.

The lady explained that Amelia (the cat’s name) was starving in a park when they found her as a kitten. They could feel her ribs. She had learned to be an outdoor hunter cat from the earliest days of her life just to survive. She was now about a year old. She’s friendly to kids, the lady said. And she will help out if you’re working out in your yard.

The clerk said to me, “Maybe you should take that cat.” She was right. I figured the chances of someone bringing in an outdoor, hunter cat, whose history we could know, was almost beyond coincidence.

The only problem was that she wasn’t fixed or vaccinated. Well, if you pick up a cat from an animal shelter, you have to pay $50 to $100 for these services, but the lady dropping off her cat (because she was getting married) was happy to give us $30 as a contribution toward the vaccines, and we no longer had to pay the animal shelter fee.

Within an hour of releasing Amelia into our backyard, she already trapped a fat vole in one of our window wells. She didn’t actually kill it, but she played with it all afternoon.

Jane’s Indifference

Jane insists on not touching the cat. When the cat took a nap in the heat, Jane said it must be pregnant. (It wasn’t.) Jane won’t let it in the house, nor hardly look at it. I’m not entirely sure why, but I think it has something to do with replaceability.

When we visited the shelter and saw three orange kittens just like our old cat, and learned that the shelter gets 60 to 80 new cats each week, it made me look at our old cat’s death in a new way. As much as Skippy was unique, he was also replaceable. A couple of days after Amelia joined our family, the emptiness and sadness for the old cat mostly disappeared.

While waiting for my wife to pick up a few groceries outside a supermarket last week, I watched new people go in and out of the store. Families, couples, children — happy and energetic. As soon as one would disappear into the store, another little family would appear on the sidewalk, just like the previous. One would come, another would go, and so on.

To some extent, we are all probably replaceable. Just like those cats in the shelter. If your cat dies, there are three more just like it waiting for adoption. Yes you’ll probably feel empty and terrible inside for a while after it dies, but you can get another one that more or less replaces the previous cat. It won’t be the same, of course. Each cat has a unique personality and behavior. You have a history and set of memories peculiar to it. But if it were to disappear one day, and never return, could you go down to the animal shelter and pick out a new one, and replace the void? I think so.

With humans, I doubt replaceability is so quick or easy or even possible. Our connections are deeper and our experiences more emotional. It takes people years to find friends or companions. Jane and my kids aren’t replaceable. But at least with pets, one cat is not so different from another.

I realize that seems shallow. It fails to celebrate the unique nature of each living creature. The thought is strangely both uncomfortable and comforting. But in my experience it’s mostly true.

Here’s a picture of Amelia.

Sometimes the cat refuses to look my way

You can see that her back is turned to me, as it was for much of the afternoon. It appears that my discussion about replaceability has been one-sided. While one cat might more or less replace another, the same might not be true of owners.

———–
If you liked this post, you will also like Jane’s Old-fashioned sorrows are (maybe) easier to bear in old-fashioned settings.

Blog Sponsors

Organizing Content as Story [Organizing Content #17]

Tom Johnson — Tue, 29 Jun 2010 14:25:00 +0000

With my ongoing series on organizing content, I left off at the question of whether blog platforms would outperform help authoring tools as a way to organize content for web environments. I had a lot of thoughts about that topic, and actually created a blog theme for a documentation project as a test, but recently I received a new project on my plate, and my attention has shifted to another angle on this same series: organizing the content within the topic itself.

I’ve been listening to Alan Porter’s presentation on “What Tech Docs Can Learn from Comics,” which he gave at the 2009 STC Summit. I was also reading his detailed post on the same topic on The Content Wrangler. Alan emphasizes the importance of implementing two main elements from comics into technical documentation: story and visuals.

One can hardly disagree with his recommendation. Any time you add either story or visuals to your content, the appeal of your content increases. When you combine story with visuals in sequential ways, as comics do, the appeal of your content increases dramatically. In this post, I’ll focus on this first point: organizing content as story.

What Is Story

Alan says a story (or narrative) includes a beginning, middle, and end. You take the reader somewhere new through a series of events.

A story has a beginning, middle, and end

Alan explains,

The second fundamental of comics is the idea of narrative [or story]. Narrative should drive and guide the reader / user along on a journey. All communication is story telling (and that is perhaps meat for a future blog post), and in story telling your narrative must have a beginning, middle and end. Even if you use a topic based authoring approach like DITA, each topic should be a ‘story’, the reader should be guided through the information and know more at the conclusion than they did at the start.

Story can be defined and described in various ways. I like to define story as any attempt to overcome a conflict, and a good story is one that requires some change to overcome the conflict. To fit this with Alan’s definition, in the beginning of the story, the protagonist encounters a problem or has some quest or yearning. In the middle, we learn what steps the protagonist is taking to resolve the problem or realize the yearning. In the end, we have the resolution.

The Element of Change

In a good story, the resolution always brings about some type of change, or comes about because of change. If you listen to stories on The Moth podcast (a storytelling podcast), you’ll constantly hear this element of change near the end of each story. For a story to feel meaningful, the protagonist always changes as a result of the conflict. Without this element of change, the story feels flat.

In technical documentation, achieving that element of change is difficult. In almost all technical documentation, the reader is the protagonist, since our point of view is second person (“you”). You (the reader) have a problem. You may be frustrated and ready to punch your fist through a door because of this problem. Through the help topic’s steps and information, you find a solution that solves your problem. Hooray, you’re much happier and complete now. That’s the basic transformation.

Tech doc will probably never go beyond this simplistic transformation to achieve anything of literary significance. For example, we’ll never have users feel a sense of the fragility of life or the meaninglessness of existence. Because of that, I think it’s best not to dwell on the transformitive element of story when applying it to technical documentation. Instead, it’s more practical to focus on the initial catalyst of all story: the problem.

Focusing on the Problem

A problem of some kind usually drives and gives rise to the story. But isn’t every help topic by default the answer to some problem? And aren’t users coming to the help content with a problem already in mind? Do we need to explicitly supply the problem, since it’s already apparent in the user’s mind?

Yes, your protagonist already has a problem. That problem is what is fueling his or her path through the help. But it can still be helpful to state the problem explicitly so that users can connect their problem to the solution you describe.

An Example

Let’s take a look at an actual example. Last year I wrote the following help topic for a calendar application that my organization is going to be using. Here’s the topic:

Subscribe to a calendar

Before you can see events for a calendar, you must subscribe to a calendar. When you subscribe to a calendar, it appears in the right column in a unique color. Your ward or stake may have dozens of calendars available, but you see events only for the calendars to which you subscribe. To subscribe to a calendar:

In the upper-right part of the screen, click Options, and then click Manage Subscriptions. The list of calendars appears with three categories: WARD CALENDARS, STAKE CALENDARS, and OTHER CALENDARS.

Click Subscribe next to the calendars you want to view.

In the upper-left part of the screen, click Calendar to return to your calendar home page.

Events from the subscribed calendars appear on your calendar. The calendar name also appears in your list of Subscribed Calendars in the right column.

The topic probably looks like a lot of topics in a help file. In a rather boring way, it explains how to perform a basic task in an application.

This topic doesn’t feel like a story. The problem is briefly mentioned at the beginning — “Before you can see events on the calendar, you must subscribe to the calendar.” And the resolution is fulfilled through the steps. But if this is the extent of story in tech doc, we may as well forget about using story as technique, because all documentation looks about like this by default.

Let’s try to rewrite the same topic with a larger emphasis on the problem. Since story usually starts with a problem (or a yearning), if we emphasize this element more, and provide a stronger resolution at the end, it will feel more story-like. Here’s that adjustment:

See Events on Your Calendar

When you first log in to the calendar, you will notice that it’s blank. No events appear, even though you may know that calendar content is available. Although it may seem like the calendar lacks content or isn’t yet set up, actually there may be plenty of events on the calendar — they are simply hidden. In order to see calendar content, you must subscribe to the calendars you want to view.

To make events appear on your calendar:

In the upper-right part of the screen, click Options, and then click Manage Subscriptions. The list of calendars appears with three categories: WARD CALENDARS, STAKE CALENDARS, and OTHER CALENDARS.

Click Subscribe next to the calendars you want to view.

In the upper-left part of the screen, click Calendar to return to your calendar home page.

Events from the subscribed calendars appear on your calendar. The calendar name also appears in your list of Subscribed Calendars in the right column. You can now view the details of each event. You can also toggle the calendar event display on or off by select the calendars you want to view or hide in the options panel.

The only substantial change I made was adding another two sentences about the problem in the introduction: “When you first log in to the calendar, you will notice that it’s blank. No events appear, even though you may know that calendar content is available. Although it may seem like the calendar lacks content or isn’t yet set up, actually there may be plenty of events on the calendar — they are simply hidden.”

I also changed the title from “Subscribe to a Calendar” to “See Events on Your Calendar.” And I added another sentence in the resolution.

Strategies for Story

It might generally be good practice to kick off each topic by describing in detail the problem that the topic solves. Although I said that the user brings the problem/conflict to the table already, putting ourselves into the mindset of a “problem-solution” format will help focus our help topics on the pain points and other most likely desired information. Explicitly stating the problem, rather than simply explaining the basics of an application, helps us maintain our focus as technical writers in the right direction: the user’s story.

On another level, though, explicitly stating the problem in detail helps the user connect his or her problem to the solution. In the above example, the user senses frustration that the calendar is blank. How would seeing a topic that says “Subscribe to a Calendar” help the user know that this is the answer to his or her blank calendar problem? There’s a cognitive disconnect if you omit the problem from your topic. Without the explicit statement of the problem, any topic might be the answer to a blank calendar. “Finding a Calendar,” “Troubleshooting Calendar Events,” “Adding Calendar Events” — these topic titles all seem like likely candidates for the user’s problem of not seeing calendar events.

Now what about the title, changing it from “Subscribe to a Calendar” to “See Events on Your Calendar.” Most readers don’t come to help files looking for basic information. They come when they have a problem. So shouldn’t our help be centered around this problem mindset and language?

That seems logical, but most help topic titles simply list tasks or actions that aren’t necessarily problems. I am not sure that changing the help topic titles to describe problems works all the time, but the general formulation of topic titles should represent the user’s problem in a closely connected way.

Although a poignant story in the literary sense will probably never be something we can achieve in documentation, structuring help topics with a detailed problem in the beginning can help make topics more story-like.

Blog Sponsors

Designing from the Content/Story Out

Tom Johnson — Mon, 28 Jun 2010 06:47:30 +0000

My wife Jane attended a Segullah writer’s retreat conference this weekend. During the conference, one of the presenters explained a common mistake many novice writers make: they look for stories to fit a pre-selected theme.

You hear the result of this strategy most commonly in church talks. Someone is assigned a topic, or has a topic he or she wants to explore. To make the talk/presentation/essay appealing, he or she looks for stories to fit the theme. The result is that each story is moralistic, simplified, and often distorted to fit the speaker’s purpose.

A better approach is to start from the story and see what theme it moves towards. In other words, follow the story to whatever theme/meaning it naturally leads you to, rather than trying to fit it into a pre-selected theme. Even if you want to take one path (in the photo below, for example, Mandan Cottages), if the story naturally pushes you toward another path (for example, Return to Sundance), go with the natural path of the story.

It’s excellent advice, but not just for writers. The advice is a cousin to the commonly heard UX principle of “designing from content outward.” It’s the same idea that people who wear shirts with a big red x through the words “Lorem Ipsum” are trying to get across. Start with the content first and then create a design for it. Otherwise your design won’t fit the content.

In a writeup on the SXSW 2010 conference, Adam Schwabe explains the importance of starting with content first. He says,

Content is all too often considered as an afterthought after wireframes and design comps have been presented to and approved by the client. Relegated to boxes as placeholders and Lorem Ipsum, too many of us take a “do it later” approach with what is most important to the user. People aren’t visiting your site to look at colours and boxes, they’re there for a purpose, and the content should be at the core of any design. (SXSW 2010: Trends and Highlights)

Just as writers start from story and build meaning from those events, user experience professionals start with content and design the frame/layout for it. It seems obvious, but few follow this logic.

If you create a design that doesn’t stem from the content, you end up with a mismatch. When it comes to add your content, you find that your content/story doesn’t actually fit the design/theme.

Blog Sponsors

Storytelling for User Experience: Whitney Quesenbery at the STC Summit #stc10

Tom Johnson — Thu, 06 May 2010 13:38:58 +0000

Whitney Quesenbery has just published Storytelling for User Experience: Crafting Stories for Better Design. In this interview I ask her to elaborate on the story behind the story, how stories compare with user personas and user stories, and how to gather stories from users. We recorded this videocast at the STC Summit in Dallas.