Flare 6 is available today from Madcap Software. This weekend I interviewed Mike Hamilton, VP of Product Management, about the new features Flare 6 contains. In this podcast, we talk about five of the new features in Flare:

• Batch processing GUI and macro targets
• Topic metadata (e.g., owner, status)
• The new link viewer
• Mobile targets
• Multimedia integration

Mike also mentions some user interface improvements, usability refinements, and hints at upcoming integrations with SharePoint later this year or early next.

Check out Flare 6 on Madcap Software’s site. And if you’re looking for Mike Hamilton’s blog, see http://madcapsoftware2.wordpress.com. You can contact Mike by email at mhamilton@madcapsoftware.com.

With the Flare 6 release, I’m particularly excited about the multimedia integration and link viewer. I signed up for the beta but have been so busy with an upcoming project release that I haven’t had time to evaluate it. Madcap was kind enough to upgrade me to version 6 as a thank-you for the podcast, so I’ll probably be posting about the multimedia integration soon (along with some screencasts using my new mic).

Blog Sponsors

• Madcap Software
• Edit Me
• Dr.Explain
• Scriptorium
• Intelligent Content
• Adobe Technical Communication Suite 2
• Alma Loveland, Designer
• Snagit from TechSmith

In this podcast, Michael Hiatt at mashstream.com presents to the STC Intermountain chapter on documentation in the cloud. By documentation in the cloud, he’s referring to our move to the web of everything we do on the computer — the running of applications, the saving of our data, the way we access and interact with all the information. He covers at a lot of ground in this presentation, touching on web 2.0, web 3.0, the semantic web, knowledge mashups, documentation mashups, lifestreaming, linked data, meshing, raw data,  and more.

Here’s the official presentation description:

Web 2.0 cloud computing, interactive social groups, and real-time global communication promise major changes in software programming, IT management, medical care, and scientific research.

So how will it affect technical communication? Significantly. Major changes are coming for all types of writers, editors, and technical developers as personalized data is streamed to Facebook accounts, web applications are mashed, and content is stored in the cloud.

Our world of in-house authoring of proprietary help files, closed doc sets, and isolated knowledge bases is coming to an end. As web creators and communicators, we need to evaluate our place in the new protocol society where content is king and authors are needed to publish entertaining and relevant information.

About Michael Hiatt

Michael Hiatt is a technical writer and manager with 20 years of experience. He has worked for software companies large and small across multiple products and varying depths of technical communication. Michael co-founded Mashstream.com, where he blogs and develops e-books, application mashups, and integrated linked data solutions.

Blog Sponsors

• Madcap Software
• Edit Me
• Dr.Explain
• Scriptorium
• Intelligent Content
• Adobe Technical Communication Suite 2
• Alma Loveland, Designer
• Snagit from TechSmith

I honestly don’t know how I’ll finish everything either. At some point, it will probably get done.

House Project Management

Being buried in tasks reminds me of advice I once heard: If you’re overwhelmed/discouraged/depressed, completing specific tasks can help you feel better. Having a list with items you can cross off helps you feel like you’re making progress.

Lately I decided to apply a bit of project triage to all the broken things around my house. I started taking notes on everything that needed to be fixed, from broken headphones to ink pen on walls to trim missing from cabinets, and so on. I have about 50 items on my list, and I’ve arranged them in P1, P2, and P3 style in a Google spreadsheet.

When I complete a task, rather than deleting it, I change its status to X and strike the font. I like to see how many tasks I’ve actually completed because seeing the list of accomplishments brightens the room a smidge.

Tonight I was working on a task–changing a burned out headlight bulb in Jane’s van–when I managed to hit my head into the corner of the hood. As the blood started to drip down my forehead, my daughter shouted for Mommy to come quickly.

It turns out it was only a little cut. Despite the blood, my spirits were high because I actually completed the task. My point here is that having a list of items that you can push through feels good. Knocking an item off the list indicates progress.

Surveying Advice

Advice on getting a handle on life’s heavy cartload is not scant. Every self-help, time management, and productivity book has something to say on the topic.

Alyssa Gregory explains that cleaning your desk can help reduce the feeling of being overwhelmed. She says “clutter is distracting and can derail your attention.” And “it’s hard to decipher what is important when everything is a mess.”

Catherine Pratt says to examine whether you really have to do everything that comes at you:

You feel like tasks are things that you “have to” do. You’re now committed and you may feel like you don’t have any choice in the matter. You must do these all these things that you’re now reacting to. Very quickly you can begin to feel overwhelmed because there just seems to be so much coming at you.

Pratt’s advice is interesting in light of a technical writer’s responsibility. Do we sometimes feel compelled to document too much, describing every single scenario, every function, every little widget and drop-down box? Do we really need the videos and online help and printed manuals and quick reference guide and release notes and context-sensitive help and live training?

eHow’s biggest advice on reducing the sense of overwhelm is to prioritize your tasks:

Learn how to prioritize. Recognize that all tasks are not created equal; meaning, there are some tasks that are WAY more important to accomplish than other tasks. Learn to recognize which tasks are of high value versus low value tasks.

I do often postpone those help topics that are cryptic and confusing. But coming back to my earlier point about lists, sometimes crossing off the easy tasks gives you momentum to tackle the harder ones.

Another self-help writer says that “breaking down a big task into smaller tasks that you are able to complete is how you get the big task done.”

The chunking method focuses on completing little tasks consistently over time to produce the larger result.

The advice for reducing the feeling of being overwhelmed is endless: Delegate tasks. Learn to say no. Focus on one thing at a time. Simplify your life. Reduce your obligations.  Meditate. Clear your inbox. Do what matters to you. Outsource. Hire a virtual assistant. The advice goes on and on and on.

Jaded on Time Management Techniques

I’m a little jaded on time management techniques, to be honest. I’m not saying they don’t work; they just seem like bandaids on a larger problem. I’ve been through the workshops, bought the time management software, and for a short time felt jazzed on some new tip or trick to manage everything. But after two weeks, all the advice runs together into the same note. And then fades.

In looking over my life, I do see patterns of achievement: I finish what compels me from the inside. If I believe in something, I do it. I find a way to get it done. I wake up early, stay up late, turn off the TV, ignore people around me, or do whatever it takes, because I believe in doing it.

For example, writing personal essays is something I believe in. I’m persuaded about the value of the activity. Sometimes people ask me how I have the time to write. It’s not about the time — it’s about the desire. Similarly, getting out from a ton of overwhelming tasks, whether at work, home, or another environment isn’t about learning to prioritize, meditate, or chunk tasks. It’s about aligning with the right cause to feel that it’s important enough to do.

Whether that’s possible with all technical documentation, I’m not sure. But having a sense of investment and pride in what you’re creating helps push you away from all distractions, from the invitations to play ping pong or to check your email. If you believe in what you’re doing and are fully invested in it, you won’t be chit-chatting all day with your colleagues, or getting lost on the web, or organizing the pens in your desk, or staring at the mountains out the window. If you believe in what you’re doing, you’ll put on headphones to block out the world around you and get lost in the work.

Now the problem returns to a theme I consistently seem to write about on my blog: it’s hard to feel driven internally by the technical writing career. I wrote about this with Aligning Yourself with a Higher Cause, Unstoppability, and Is Technical Writing Boring?

The problem is that technical writing jobs are not inspiring enough on their own to turn people into believers of the cause in the degree necessary to finish all overwhelming tasks. When it’s 5 p.m., I turn off the computer and go home. No one stays until 10 pm at night writing instructions because he or she is just so driven internally and fascinated by the technical writing  job that he or she wants/needs/has to stay despite all other commitments, requirements, and obligations. Technical writing isn’t so engrossing that you find yourself up at 2 a.m. thinking about solutions and innovative new techniques and experiments you want to try.

Sure, that might happen sometimes. Sometimes I stay late, sometimes I wake up thinking about a technical writing problem, and sometimes I get engrossed in online help and wikis. But not to the degree that would be necessary to make me fly above all these tasks that never get finished. Not to the degree that I would rise at 5 a.m., go to the computer, and start organizing and editing my online help.

In the end, when I have a ton of tasks to do and no room to breathe, I do end up prioritizing those tasks I believe in more — screencasts, quick reference guides, context-sensitive help. I put off that 150 page PDF manual until the last couple of weeks.

Given the inability to tap into a higher cause, the lower-level time management and efficiency tasks are a welcome gimmick. I have my lists with tasks I’m crossing off. I’m clearing off my desk. I’m evaluating whether I need every single help deliverable. I might even start using that old Franklin Covey software I uninstalled years ago.

Blog Sponsors

• Madcap Software
• Edit Me
• Dr.Explain
• Scriptorium
• Intelligent Content
• Adobe Technical Communication Suite 2
• Alma Loveland, Designer
• Snagit from TechSmith

Some writing teams sit together. They chum with each other all day long about commas and online help layouts. At my first job as a technical writer, I sat in a long row of cubicles we figuratively called “The Technical Publications Office.” All day long I could listen to my colleagues say things like “Oh my goodness, this guy is writing fused sentences.” Or “Don’t you just love it when all your images disappear from Microsoft Word!” or “Hey Tom, can you help me with something?”

You know what I’m talking about — the camaraderie of being in a group of writers, exchanging comments about projects, bantering about this or that. It’s a cozy, comfortable feeling, being surrounded by other literary kind.

Agile Environments

It’s not like that in my current agile environment, though. In many agile environments, you have to forge your own way, often sitting away from your writer colleagues, embedded among QA, developers, interaction designers, and managers on a project team. Although I’m on a team of eight writers, most of us are spread out in different departments, assigned to different projects. As a result, writing documentation can often be a lonely, long experience alleviated only through Pandora, Twitter, IM, the incoming comments on my blog, and my wife’s scandalous posts.

I know it would be a lot more fun to be desk-to-desk with all the other writers in the organization. We could stop every now and then to feign horror at grammar atrocities or mock the edits our SMEs make. We could easily review each others’ work, provide feedback about parallelism with topic titles, compare TOC layouts, or discuss the style guide.

But I’m more effective sitting next to other employees working on the same project. Sometimes I wear a QA hat and point out bugs (and explain/show them to developers). Other times I coordinate with project managers about customer feedback and concerns. Other times I ask developers to explain how something works or why they built a function a certain way. You need to be close to your project team to interact with them, right? Proximity has an impact on communication, no doubt. But I’m not so sure ours is the best model to follow.

The Book Sprint Model

Last month leaving an STC meeting, as I was walked through an windy parking lot to my car, I caught up with a colleague, Joe, who works as the sole technical writer at a nearby company.

We talked a little about the meeting. And then he said, “Sometimes I have so many questions. I mean, do you ever think we have the whole model wrong?”

“Huh?” I said. “What are you talking about?”

“You have eight writers in your team. Why don’t you all just sit down and tackle a project together and knock out the documentation in a week?”

I’d heard of this model applied to book sprints with open source projects. Anne Gentle has written extensively about book sprints. Tomas at BookSprint Central explains that coming across the idea of the book sprint was the “most important epiphany of [his] professional career.” He explains how few people rarely have the time to sit down and write an entire book themselves. It simply never gets done. He says,

I also knew that there was no way i was going to be able to spend all my evenings for a year writing such a book even if i wanted to. Which i didn’t. And i had a feeling that while i’d collected a network of incredibly smart people, with boundless experience in this field, everyone else felt mostly the same as me when it came to evenings and years. But I also knew that i could convince almost anyone of these incredibly smart people to give away a week of their time to such as good cause. So there were the constraints. Have: One week of time each from a bunch of smart people. Need: Finished book.

His solution was the book sprint. And it worked. He flew in a group of smart, knowledgeable people and sat them down in a room for a week to write. They produced a completed book, which was downloaded thousands of times and translated into numerous languages.

I like the book sprint idea, quite a bit. It reminds me of the Amish barn raising, or a group of guys pulling together to help someone move.

In fact, as far back as 2005 at a conference in Raleigh, I remember Rick Sapir arguing against the one-writer-for-the-entire-project model that’s so common in documentation. Why not have several writers work on various parts of documentation? he said. Everyone takes a little chunk of the application and writes documentation for it. The idea that one writer creates all the documentation for a project is an old model, he explained.

At the time, I disagreed. I said it wouldn’t work because you can’t write effectively about one aspect of an application without understanding the whole. And to understand the whole takes months of exploration and learning. Not to mention the dozens of project meetings. If everyone has to devote the same amount of time learning the application to write about one small part, isn’t that inefficient?

I’m also wasn’t sure how help can be put together in such an independent way. Although each topic in a help system is usually a semi-independent chunk, how do you know that the topics Writer A contributes don’t overlap, contradict, interfere, or otherwise jar with the topics that Writer B contributes?

On the other hand, the group collaboration model has its benefits. Multiple writers working together can see an application from various points of view. The writers are less inclined to become myopic and routine. They can more freely bounce ideas off each other, make more informed decisions about content and layout, and generally approach the application with twice the brain power.

Book Sprints with Community Projects

One day I’d like to try the book sprint model in a corporate setting. However, since major changes within a large organization are hard to implement, it might be more practical to do a book sprint with our community development projects. We have more than a dozen community-driven projects (most of them small) in which the community participates in the requirements, development, and design. This is one of the cool and interesting aspects of working for a nonprofit organization. Some members want to volunteer their time and talents to further the work. We’ve been trying to figure out a way to harness their talents.

Previously, I had been pitching the incentive to contribute tech docs as an opportunity to get experience for your portfolio. But that route wasn’t so effective. Participation was slow and inconsistent.

Next time, I might contact 10 or so community colleagues interested in helping out and invite them to participate in a book sprint. It could be an entire day, one that we dedicate to documenting just one project. An entire Saturday, or something. I doubt I would fly people out to Utah and put them up in a hotel room for a week, because most people can’t take a vacation from their regular jobs for this, but I can see people dedicating a Friday or Saturday or even Sunday to remotely contribute toward a project they believe in, especially if the idea is packaged in the conceit of a “church book sprint.”

Whether you’re integrated into an agile project team and away from other writers, or together with multiple writers on the same project, increasing collaboration is key.  Rick was right: the single writer working tirelessly in solitude on a manual that he or she authors from start to finish is dead.

Blog Sponsors

• Madcap Software
• Edit Me
• Dr.Explain
• Scriptorium
• Intelligent Content
• Adobe Technical Communication Suite 2
• Alma Loveland, Designer
• Snagit from TechSmith

So when she received a B+ in reading, it threw me off guard. In our parent-teacher conference, I asked the teacher, “How are you measuring her reading ability?”

It turns out one of Sally’s weak points is in reflection and analysis. She reads like a whirlwind, but she doesn’t reflect enough about what she reads.

The teacher showed us one-line, terse responses from Sally. Hmmm, she seemed to answer the question, but not in a critical or reflective way. It occurred to me that we never really practiced reflection at home. We read Sally plenty of books as a child, but did we ask enough questions of the books we read?

To practice, I’ve started a new routine. After we read scriptures (the only thing we read together as a family), I invite the kids to ask three questions about what we read.

Asking questions is one of the most powerful ways to open up a text and begin a discussion. It’s not a new technique, of course, but it’s one a philosophy professor in college taught me years ago. The professor asks questions about everything. He hardly stops to answer the questions he raises. It seems he’s more interested in asking questions than finding answers to them. Coming up with the interesting questions seems to be his point.

I’ll give you an example. Take a familiar story — Snow White. If the philosophy professor were reading Snow White, his questions might go like this: Why did the Queen want to be fairest of them all? What does it mean to be fair? If the wicked queen was a sorcerer, could she not make herself the fairest? Did Snow White have any magic powers of her own? Why did the author choose coal-mining dwarfs as her rescuers? Who is truly being rescued? What’s the relationship between the dwarfs and the queen? And so on.

I admit my hypothetical questions aren’t very good ones. For an actual sample, see his post analyzing Abraham.

Questioning an Interface

Asking questions is not only a good way to raise insight about a text, it’s also a good way to investigate an interface. As technical writers, we should be asking a lot more questions than we often do. It seems that after we learn the main functions and purpose of an application, we document the core tasks and continue on.

But if we were to apply a  more in-depth questioning rhetoric, we would uncover a lot more. For example, I recently documented how to use a new calendar application. I covered all the main tasks and roles. But did I cover all the gaps where questions might be hiding?

Running through a sample screen, for example, the home page, with my questioning rhetoric, I might ask, Why is the calendar blank? How do I create a new calendar? What is the definition of a calendar? How does this calendar compare to Google’s? How does it compare to Outlook? Why not simply use another existing calendar? If I’m using another calendar, can I import my existing content? What does it mean to “subscribe” to a calendar?

I could also put myself in the shoes of another individual in a specific scenario and generate questions. Now I’m my ward activities coordinator looking at the calendar. I have a paper calendar for the entire year already printed out. Here are my questions now: If I’m comfortable using my existing calendar software, can I keep using it? Why is this system better than the previous one? Does this calendar send notifications to the subscribers? Does it reserve room locations? Does it warn you about conflicts? How do I know if a calendar day is free?

Now let’s pretend I’m the ward bishop. Here are my questions: Can I keep confidential appointments in the calendar? How do I know it’s secure? How do I give viewing rights to my secretaries? Will the older members of my ward use the online calendar? How should I train the group leaders? Can I print this out and insert it into binders?

I could keep asking questions from different perspectives and problem scenarios until I saturated all the information users might want to know.

Too Much Information?

At some point, if I answer every question I ask, I begin to generate too much information. The application is a simple calendar, much like Google calendar. Should the help file be 150 pages? No one will read that much.

Mike Hughes says help should be a mile wide and thirty seconds deep. While I like to err on the side of too much information, having hundreds of topics to anticipate and answer every possible user question is a little extreme.

On the other hand, if you begin eliminating questions, reducing the help content to a bare minimum, don’t you do a disservice to those who might need the information? This is where Mike’s 30-seconds rule might come in. Perhaps keeping the topics short allows you to write and maintain more topics?

Ending Thoughts

Regardless of how many topics you decide to include in your help, asking questions is a tool that can serve you well in all areas of life. Learning to ask questions is the secret to having endless fodder for your blog. It helps you keep an open mind and converts a static reading experience into an engaging one. For my little third-grader, asking questions may help her develop a lifelong habit of reflection. She might even become a philosopher.

Blog Sponsors

• Madcap Software
• Edit Me
• Dr.Explain
• Scriptorium
• Intelligent Content
• Adobe Technical Communication Suite 2
• Alma Loveland, Designer
• Snagit from TechSmith

Despite these benefits to the project team, in a recent triage meeting with the lead developer, as we discussed the bugs that needed fixing, it looked like the world was on his shoulders. I realized that developers like to hear about bugs as much as writers like to hear about typos and grammar errors in their writing. With many of the bugs, the developer would softly say, “Okay, we can look into it.”

It made me wonder. If developers only hears about bugs, problems, quirks, errors, and other issues, where’s the motivation to code?

In a recent post on Joel on Software, Joel Spolsky stresses the importance of giving positive feedback to developers, not just negative:

A great tester gives programmers immediate feedback on what they did right and what they did wrong. Believe it or not, one of the most valuable features of a tester is providing positive reinforcement. There is no better way to improve a programmer’s morale, happiness, and subjective sense of well-being than a La Marzocco Linea espresso machine to have dedicated testers who get frequent releases from the developers, try them out, and give negative and positive feedback. Otherwise it’s depressing to be a programmer. Here I am, typing away, writing all this awesome code, and nobody cares. Boo hoo.

In other words, programmers need both positive and negative feedback on their work in order to grow. But when I’m wearing my testing hat, all I’m finding are problems. This doesn’t work. This looks out of alignment. This lookup field is returning the wrong results. This button doesn’t respond when I edit the item. This page isn’t styled like the prototypes. This modal takes too long to appear. When I click this button twice, the rich text editor blows up. And so on.

Logging 25 bugs in one day was sadistically fun in the moment. But in retrospect, especially during the triage meeting with the developer present, the weight of the bugs was like sin on a priest’s back. Every new bug I added seemed to make his heart beat faster into anger or slower into death.

I’m sure that developers like to solve problems. So it’s not as if problems are necessarily depressing in themselves. But as I’m logging bugs in the bug-tracking system, there’s no way to balance out the negative with some positive praise.

A few days ago, near the close of the day, I was investigating a complex scenario in the application I’m documenting. It was a new feature we built into the application that added a level of sophistication the previous version lacked. I thought I would discover a bug, but instead the application worked beautifully. Elegant, fast, and clean. I stared at the screen for a minute, in awe at the neatly arranged display of information. This is perfect, I thought.

But there was no where to log my praise in our bug tracking system. Apart from the occasional iteration meeting where we demo new features, there is no built-in mechanism to provide positive feedback to developers. I was the last one at work that day, so I just went home.

A System of Positive Feedback

Exactly how could I implement a system of positive feedback for developers? Would it be a waste of time? Do I fire off an email now and then? How do I even know which developer coded the page I’m looking at?

The next day I decided to ask a developer who sits next to me: “If all you ever see are problems and bugs, and you never see the praise, how do you stay motivated? Don’t you need a balance of both positive and negative feedback on the work you do? JIRA only allow us to give you the negative.”

He thought for a minute. At first he acknowledged that he did receive occasional user feedback from both users and the project manager (the project manager has an especially encouraging attitude). The developer also explained that he gets to work on an application that matters to him personally, which is a reward in itself. But then he paused and thought a bit more.

“I think at some point you have to find your motivation from within yourself,” he said. “Sure it’s nice to hear positive feedback, but that’s not ultimately what keeps me going.”

Praise as Manipulation

He’s exactly right. In fact, a system of praise might be the worst feedback you can give developers. According to Alfie Kohn in Five Reasons to Stop Saying “Good Job”, telling your children “good job” can distort their intrinsic desire to do an activity to a desire for the “good job” praise. Kohn writes,

The more we say, “I like the way you….” or “Good ______ing,” the more kids come to rely on our evaluations, our decisions about what’s good and bad, rather than learning to form their own judgments. It leads them to measure their worth in terms of what will lead us to smile and dole out some more approval.

… “Good painting!” may get children to keep painting for as long as we keep watching and praising. But, warns Lilian Katz, one of the country’s leading authorities on early childhood education, “once attention is withdrawn, many kids won’t touch the activity again.” Indeed, an impressive body of scientific research has shown that the more we reward people for doing something, the more they tend to lose interest in whatever they had to do to get the reward. Now the point isn’t to draw, to read, to think, to create – the point is to get the goody, whether it’s an ice cream, a sticker, or a “Good job!” …

In short, “Good job!” doesn’t reassure children; ultimately, it makes them feel less secure. It may even create a vicious circle such that the more we slather on the praise, the more kids seem to need it, so we praise them some more. Sadly, some of these kids will grow into adults who continue to need someone else to pat them on the head and tell them whether what they did was OK. Surely this is not what we want for our daughters and sons.

In other words, as soon as you start praising your children, they seek more praise, so that instead of doing an activity out of the pure enjoyment of it, they do it for your praise. Your praise has begun to manipulate their behavior. When the praise stops, the children lose interest in the activity.

In the developer scenario, implementing a system of praise might similarly diminish the intrinsic motivations of developers. It would manipulate the pure enjoyment  they feel when they solve problems, figure out solutions, and conquer cryptic, seemingly impossible scenarios. If you begin patting developers on the back each time they do something right, soon their motivation switches from internal rewards to external praise.

Not Just Advice for Children and Developers

The other day I was eating lunch with some colleagues. One of my colleagues said he was interested in starting a blog, but wanted to know what to do when he publishes a new post and only hears crickets. In other words, what do you do if you write and no one provides any feedback? If no one says, Good job, Tom. Way to go, Tom. Excellent post, Tom. I loved reading this, Tom. Then what do you do? What happens if all you hear is silence?

When silence is all you hear, you have to find an intrinsic motivation for writing. You have to write for a higher purpose, more than simply writing for feedback and praise. You may find yourself writing because you love story, or because you enjoy thinking about ideas, or because you like playing with language.

Comments may provide short-term feedback about the effectiveness of your writing. But in the long run, “good job” comments are detrimental to stoking the writing muse. The day the praising comments stop, your motivation wanes.

So now I’m back to logging bugs, but this time I do it without feeling mixed about where to log the praise. I’m not against giving feedback to developers about the application interface and functionality. Analytical, reasons-based feedback isn’t detrimental, because it helps people evaluate their work from another perspective. But when I have nothing to say besides “Good job here,” I’m witholding my comment.

Blog Sponsors

• Madcap Software
• Edit Me
• Dr.Explain
• Scriptorium
• Intelligent Content
• Adobe Technical Communication Suite 2
• Alma Loveland, Designer
• Snagit from TechSmith

Oh, that field? he said. I never really understood that feature, so I left it alone.

The user wasn’t a novice. He used this application several hours a day, if not more. How could he be so comfortable leaving alone a feature that could be integral to his workflow, which could save him hours of time and make his life easier? I could hardly believe it.

Knowledge Intake Thresholds

As I related the feedback to my colleagues, they noted how we often do the same thing with applications we use. For example, I use iTunes to download podcasts, create playlists, and sync the audio to my iPod. I know iTunes can do a whole lot more, such as create smart playlists based on the music I most often play, but I’m not interested in that. I don’t quite know how to set it up, and frankly I’m happy with my current level of understanding.

Photoshop is another example. I can get by in Photoshop all right. Only when I absolutely have to learn something, such as layer masks, do I start pushing my knowledge deeper by going into the help.

I often give one-on-one WordPress training. This past Saturday I scheduled a two-hour call with someone implementing a wootheme. At about an hour and a half into the call, I could tell the person’s brain was saturated. I had hit the threshold on her knowledge intake for the day.

My own knowledge intake threshold maxes out at about an hour. This is why classes at schools aren’t longer than 50 minutes. After an hour, the amount of new knowledge you can continue to absorb goes downhill.

Long-Term Learning

As technical writers, it’s hard to feel empathy for users when they refuse to learn. It’s all in the manual, if they would just read it, we often say. But we have to remember that we spend months ramping up on a software application — users don’t. Our first experience of the application is usually in a development environment where features are only half-coded. As time passes and new features are developed, and we attend project meeting after meeting, we slowly add the new knowledge to what we’ve already learned. After six months of gradual ramping up, we’re experts on the application. We then try to teach users to be experts in a day, or more realistically, in about 20 minutes.

Do you see the problem? We get six months to learn little by little, being paid handsomely to do so. The user gets 20 minutes and must often take time out of his or her schedule to do it. It’s no wonder the user doesn’t naturally move into the expert knowledge range.

A more practical way to learn new software is to approach it bit by bit. An hour a day over the course of a month can be more helpful than a crash course. But how do you keep the user learning every day or week?

Strategies to Keep the User Learning

I’ve seen at least four methods to help users keep learning an application:

• Daily tips. Some applications show a daily tip in an attempt to increase your knowledge little by little. However, these tips are often as successful as ad pop-ups on websites.
• Regular newsletters. Some companies provide a regular newsletter about their products. For example, TechSmith provides a periodic newsletter that usually has a couple of tips for using Camtasia Studio and Snagit. I scan this newsletter and will watch a video tutorial on a feature I’m unfamiliar with.
• Product blogs. Some products are robust enough that the company has an entire blog focused on the application. Microsoft Office is one example.
• Interface tips. When there’s a new feature added to the application, the interface often highlights what’s new through a little bubble caption. This is common in Gmail.

Encouraging Desire

Besides these methods, I’m not sure what you can do to help users continue to increase their knowledge of an application. The problem is that even if you provide the means for advanced learning, whether through tips, newsletters, blogs, or interface notes; users already familiar in performing a core set of tasks are inclined to remain in their comfort zone.

In their minds, they already know the application. Or they know it well enough to get by. As with most things in life, the problem in helping users learn isn’t so much strategy as awareness and desire. They often don’t know what they’re missing. So they don’t care about missing it.

Blog Sponsors

• Madcap Software
• Edit Me
• Dr.Explain
• Scriptorium
• Intelligent Content
• Adobe Technical Communication Suite 2
• Alma Loveland, Designer
• Snagit from TechSmith

This bothered me. As a good practice, we’ve tried rounding up the kids to read before. But each time this proved somewhat disastrous. The problem is the wide range of ages. I’m 34, Jane 32, Sally 9, Susan 5, and Spot 3. Try holding a meaningful discussion when everyone is at a different comprehension level. What Susan can grasp isn’t on the same level as Sally. And Sally is far beyond Spot, and so on, to say nothing of Jane or me.

The situation isn’t too unlike the problem with technical levels and user documentation. Power users need one kind of documentation, beginners another. It’s hard to satisfy both groups with the same content.

Or so I thought. I haven’t solved the dilemma with user documentation. But with my little family, I’ve learned that story is the common language that everyone speaks. Regardless of age, when you start telling a story, everyone listens.

So we’ve stopped reading by the line. Instead we focus on the story. I read ahead, get the details of the story down in my mind, and then narrate it to my children. Sometimes Jane tells the story. Whereas before Susan would mischeviously close my book, she now listens eagerly. Sally listens and retains the most minute detail. Spot plays quietly with barbie dolls.

When we think about writers who are gifted with language, too often the discussion revolves around articulate expression, the ability to paint vivid imagery, or some other literary talent. Despite these flourishes, the most powerful form of language is story. Story is what has meaning. The stories you tell about yourself, the stories you learn about the world around you, and the stories others tell you form your world view and shape how you understand and interpret nearly everything that happens to you.

Story and Documentation

Story, or narrative, is not a stranger to the world of documentation. As I said, story is the language everyone speaks. In a recent post on The Content Wrangler, Alan Porter says narrative is one principle we can learn from comics and apply to documentation. Alan writes,

The second fundamental of comics is the idea of narrative. Narrative should drive and guide the reader / user along on a journey. All communication is story telling [...] 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.

Alan’s assertion that “all communication is story telling” is a strong one, and much of it hinges on his definition of story. To some degree, a story must have a beginning, middle, and end, he says. He gives the following example of story from Chrome’s comic documentation:

An example of narrative in documentation

If you strip out the visuals and just leave the text, is that story? What really is story beyond simply having a beginning, middle, and end?

To rewrite the above into a more narrative form, it might look like this:

As you surf the web, much of your experience is defined by your browser. But browsers crash when they can’t load scripts or handle the heavy file sizes of websites. Rich media, in the form of video, graphics, and sound, can make your pages load slowly and freeze up your memory. Malicious scripts, worms, and other malware can pass from your browser to your computer, infecting your system with viruses. To avoid these problems, you need a stable, fast, and secure browser. That’s why we built Chrome…

To emphasize the story, I tried to highlight the challenges that you (the protagonist) face when you cruise around the web with your browser.

To be a good story, though, you need several other elements. Good stories start out with some kind of conflict, for sure. This gives the protagonist purpose. The initial conflict sometimes creates other conflicts, which then cross into each other, complicating the situation. The resolution often comes about as the protagonist changes. Without some change in the protagonist’s attitude, stories feel flat.

To make this a good story, then, I would need to talk about the effort to create Chrome, the challenges they faced, epiphanies at moments of absolute frustration, and other flashes of insight that helped make the connections and leaps necessary to build the browser.

Another Approach to Story and Documentation

Although the Chrome example works, much of documentation involves procedural steps, not background on how or why an application was made.

If story is the common language everyone speaks, and the most powerful form of language, what should the role of story be with procedural, step-by-step documentation?

Some procedural topics could actually be written like the example above, setting out the problem and explaining how to solve it through the software you’re providing. Focusing more on the problem is a good strategy. Here’s a page out of the CSS Cookbook that does exactly that:

The CSS Cookbook starts out each how-to topic by defining the problem that the solution answers

Notice how the author begins by defining the problem. The solution then provides the answer to the problem. This problem-solution format is not unique in their approach. Almost every topic in the book is set up this way.

Imagining Persona-Driven Problem Scenarios

Another way to incorporate a narrative perspective into documentation is by imagining specific use cases. Ginny Redish says to imagine not just the questions your users will have on a page, or the types of users who will come to your site, but to imagine specific users with specific problems.

For example, as you’re evaluating the content on your airline site, you may have already defined various personas for your users. But have you imagined your users with specific, real problems? John is a 34-year-old bank executive who needs to quickly cancel his flight to Hong Kong because of a family emergency. Now you have a problem that your content will attempt to answer. Sally is an impatient, scatterbrained secretary who was just thrown into her role last week and has to figure out how to set up a meeting in the new system by tomorrow morning. Again, you have both a persona and a problem.

Additionally, you can also integrate examples of actual users and common scenarios into the documentation. You could describe a typical scenario that Kate goes through to process bank statements in the system and what she does when the transactions don’t balance. This form of narrative is a technique often used in in e-learning.

The Story On and Off the Page

Although I’d like to believe otherwise, implementing story in the traditional narrative form will probably always be a challenge with technical documentation. Story thrives in the literary arts, not in manuals. However, although story might not apply to every page of instructions, every topic in your help can be an answer to a struggle the user is having.

In this sense, the user supplies the conflict and the documentation supplies the resolution. The change occurs when the user’s sense of frustration subsides with an aha! moment. Because of this, we cannot create the full story in our documentation. Instead, we’re only an actor playing a part in a larger story taking place on and off the page — the reader’s frustration with a problem, his or her turn to the help, and the resolution and change of attitude the help topic brings.

Blog Sponsors

• Madcap Software
• Edit Me
• Dr.Explain
• Scriptorium
• Intelligent Content
• Adobe Technical Communication Suite 2
• Alma Loveland, Designer
• Snagit from TechSmith

Information exclusion is fairly common. Just last week I learned about an application that had a new version nearing release in a week, but the developers hadn’t told me about it. I documented the previous version, and although the developers made the help button more visible, they never told me they were releasing a new version. They never mentioned to me what they had updated.

In their minds, they hadn’t updated much. A few enhancements here and there, but did any of it affect the help? They didn’t know because frankly, they probably never read the help. In their minds, help had been checked off the list weeks ago. There was no need to revisit it. Besides, they were mostly working on bugs and fixes, not new use cases.

When I learned, through a general department meeting, that a new version of the application was being released in a week, I scrambled back into the application to find out what had changed. As I moved from topic to topic through my help and the interface, I spent the next 30 hours making updates to the help content. I had to scrap all of my videos, as they were no longer accurate. I added some new topics, removed others. Fundamental terminology changed, and new functionality had been added.

As I sat there updating the documentation against the clock, I could hardly believe I hadn’t been notified. C’mon, were they really going to release this without telling me what needed to be updated in the help?

I was a bit upset for a few days, but under too much pressure to really think through the why of the situation. Instead, I was heads-down, hands on the keyboard, frantically making updates and logging bugs and trying to fix things before they shipped it out the door.

Though I tried not to think this way, I started to resent the project manager a bit. I had rarely been invited to a project meeting or scrum. I had to persuade the project manager that their app needed comprehensive help in the first place. Wasn’t the project manager savvy enough to know that with each update to the interface and functionality, the help needed to also be updated?

This is a situation you’ve probably run through dozens of times. Once early in my career something like this happened — the interface kept changing on me, and no one ever informed me about the changes. One of my senior colleagues looked at me and said, with a smug look on her face, “Welcome to our world.”

In those early days as well as the other week, when I experienced developer neglect and suffered a lack of information, I felt marginalized. I tasted the second-class citizenship status that so often takes place in IT organizations with technical writers. The tech writer is the last to know about interface updates, if anyone even bothers to let him or her know.

The perception of information exclusion, whether real or not, is so common among technical writers that it might even be classified as a complex. If you suffer from an information exclusion complex, you’re disgruntled at project teams for not telling you the information you need to do your job correctly. The project’s information door has been shut on you, and you must kick your foot under the door to wedge it open.

Well, I have started to figure out how developers tick, and I recently discovered something that has helped me break free from my information exclusion complex.

How Developers Tick

I didn’t piece this together all at once, and it is still a picture that is forming in my mind, but it’s compelling. At the heart of how developers, quality assurance (QA) engineers, and project managers interact is through a bug/enhancement tracking system called JIRA. In your organization it may be something else, but the concept will likely be the same.

In my organization, every time QA engineers find a bug, they log it in JIRA. Every time project managers have an enhancement to the existing functionality, they log it in JIRA. Every time developers fix something, they log it in JIRA. Every change to the application gets logged and tracked in JIRA.

The project manager and QA lead assign the items in JIRA to developers. Developers and QA comment on each of the JIRA items, noting challenges or obstacles to the JIRA item. Project managers give each JIRA item a priority level, so that P1s get the most critical attention, while P3s are usually not worked on at all. In short, JIRA stores all of the necessary information for the project.

I have simplified things here, because even though all important and changing project information is stored in JIRA, the JIRA system itself is like a maize to navigate. In one of my projects, we have nearly 2,000 items in JIRA, all with various priority levels, version release assignments, sources, dates, comments, and other details. Navigating JIRA can be like looking at a street map of Mexico City and trying to decide where or how to go.

Despite the challenges, keeping up with JIRA, I’ve learned, is the key to staying on top of a project. It’s how the developer mind works. Once you understand this, it will help cure all symptoms of the information exclusion complex. If a developer logs something in JIRA, whether it’s a bug, a fix, an enhancement, a user story, or even an update the server the application runs on, he or she expects that everyone else on the project who has access to JIRA will see the update. The developer assumes everyone is as JIRA-savvy and JIRA-driven as he or she is.

As technical writers, we often scorn users who are too slow/lazy to read the manual (RTFM). The corollary for developers is to scorn technical writers who are too slow/lazy to read JIRA (RTFJIRA). See how the tables are turned?

Leveraging JIRA to Influence Changes

Don’t be intimidated by JIRA, or whatever bug tracking software you use. JIRA is your best friend, because now that you know the secret — that JIRA controls all information about a project — you can start to leverage this information source to influence updates and changes to the application as you see fit.

You know that capitalization error on the home page of your app that is driving you nuts? Stop complaining about it in project meetings. Just log it in JIRA and it will probably get done. How about the error message box that says, “Object reference not set to an instance of an object.” You’ve been telling developers for months that no one will understand it. But they aren’t waiting for an email from you to specify how to fix it. No, they’re waiting for the item to appear in JIRA. Like a cook waiting for an order, developers will simply see the request on their screen and get to work.

Not every thing you slip into JIRA will get implemented. The tough fixes will be procrastinated, just like you have procrastinated the toughest help topics in your help. When developers feel weary and tired, and when they’re winded from playing too much ping pong, they’ll cherrypick the easy JIRA items that require nothing but simple text updates — your capitalization pet peeves, the label misspellings, those inane on-screen messages that developers typed while they were half-asleep. As long as you stick your requests in JIRA, they will eventually get done.

Still a Few Surprises

Although I’m following JIRA more carefully now, I still get surprised by project release dates I wasn’t anticipating. But this is only because I fail to check the project items and statuses. Lately, however, I have subscribed to the RSS feeds of the comments and issues in JIRA I want to track. (By the way, RSS Bandit is one of the few RSS readers that can pull authenticated RSS feeds behind your corporate firewall and send you updates when additions are made.)

Even if I’m surprised every now and then by unanticipated changes, I’ve completely shed the information exclusion complex. I’m not frustrated if developers don’t tell me about interface and functionality changes. In an agile environment, there’s no way they can keep me updated on an individual level about everything that changes. And I wouldn’t want them tapping on my shoulder all day anyway. I can learn most of what I need to know just sitting in my chair, looking at my screen, submitting new items to JIRA or looking at those JIRA items that have been submitted. Every once in a while I drop by the developers’ desks, but more to say hello than to ask what’s new.

Blog Sponsors

• Madcap Software
• Edit Me
• Dr.Explain
• Scriptorium
• Intelligent Content
• Adobe Technical Communication Suite 2
• Alma Loveland, Designer
• Snagit from TechSmith

jQuery is the new Javascript. It provides smooth functionality that shows and hides components, slides objects around, and animates graphics in a sexy way. As an example, ProPhotoBlogs’ support section incorporates jQuery functionality. And the drop-down menus on Will Sansbury’s site are also jQuery driven. Here are a few jQuery animation effects. And slide-down effects. And fade effects.

Alistair says he feels satisfied he made the right choice about adopting Flare as a help tool because of this extensibility. Because of the XML and CSS standards that Flare is built on, Alistair can add a reference to the jQuery script in the header, add functions in the page body and toolbar, and hook into other technologies to customize the display.

For detailed step-by-step instructions on inserting functions into Flare’s Webhelp toolbar, see Alistair’s post, Adding function buttons to to the Madcap Flare Web Toolbar.

I like Flare for much of the same reasons as Alistair. I haven’t integrated jQuery scripts into Flare yet. But knowing that I can do it if I wanted to is encouraging.

The next question is what functionality we’re missing from Webhelp. Is jQuery just the latest gee-whiz, bell-and-whistle technology? Or is it functionality that will persuade users that the help is worthwhile?

Alistair says he created a button that shows a direct link to the topic the user is viewing. And he hooked into a custom glossary database. He also integrated his own show/hide functionality and a bookmarks feature. Granted, some of that functionality already exists to some degree in the existing Webhelp buttons, but Alistair’s company had custom needs.

One button I’ve added to Webhelp is a Contact button that allows the user to send feedback to the project team. I would like to incorporate jQuery scripts to make screencasts pop-up in a modal that dims the background. I’d also like to make screenshots expand to full size when the user clicks them (similar to Flare’s new thumbnail feature). The way graphics slide down smoothly with jQuery is more elegant than the built-in drop-down hotspot functionality Flare provides. (I imagine you have to work in the code view to integrate all of this.)

I’m not sure to what extent other tools can hook into the same technologies. But it is important to have this potential — so that help authors can keep pace with the developments and technologies of the web.

To listen to Alistair Christie’s podcast on extending Flare with jQuery, see Unscripted Screencasts and Flare Extensibility.

Blog Sponsors

• Madcap Software
• Edit Me
• Dr.Explain
• Scriptorium
• Intelligent Content
• Adobe Technical Communication Suite 2
• Alma Loveland, Designer
• Snagit from TechSmith