Using social networks to collaborate on content development

Social networking has exploded over the past few years. Corporations added Facebook pages to extend their websites, product user groups have sprung up on LinkedIn and Yahoo and a host of other sites, and even Twitter’s gotten in on the action.

But for most part, it feels like companies are using social networks for two things– marketing or customer support.

How many are leveraging social networks to develop technical information?  A few months ago, I read and reviewed Confluence, Tech Comm, and Chocolate by Sarah Maddox, a technical writer with some great ideas for doing just that. One of my favorites? Using Twitter to connect users in a high tech Dragon Quest, which was really a way to tackle a complicated integration process.

Technical Information has a bad image…  everyone hates reading instruction guides. They’re long, they’re usually boring, and don’t always dive deep enough into the content to truly help users. And the process for fixing them is even longer.

Social networks mean we — technical writers, not Marketing, not Support, not even the contractor hired to create some survey — can have direct access to our audience.

How do we make it happen?

I see this is a two-phase process. First, you have to get people to listen to you. Second, you have to encourage them to help, make it too much fun –as Sarah did — not to. T

Yeah, easier said than done. I know. But it’s a start.

Phase 1: 

In the Listening phase, we need to show our audience, our end users, what’s good about our technical content. Find the success stories, the examples when a revised procedure solved a customer’s problem and share them — Twitter, LinkedIn, etc. Get the word out that Technical Information is more than long, boring manuals.

Phase 2: 

In the Encouraging phase, we need a mechanism that makes it easy for readers, the users of our information, to report problems, suggest changes or additional topics, and even submit their own content. Wiki, website, or even blog technology works well, depending on the scope of your information set.

That’s as far as I’ve gotten.

Are you collaborating with your customers on content development? How are you doing this? Where do social networks fit into your process? 

50 Shades of Tech Comm – How to Clean a Mouse

Unless you’ve been living under a rock, you probably heard that the Fifty Shades of Grey books out-sold Harry Potter. Famous for their explicit sex scenes, the trilogy has been lampooned by everyone from late night TV hosts including Saturday Night Live to serious authors.

I actually liked the Fifty Shades books; thought they were fun so I thought it might be even more fun to see if technical communicators might be able to leverage the books’ popularity. Without further ado, I present to you my Fifty Shades of Tech Comm, in the hopes it will do for RTFM* what Fifty Shades of Grey did for BDSM.

 * Read the F*cking Manual 

 

HOW TO CLEAN A MOUSE 

With a frustrated sigh, Annabella Heron tossed her long chestnut locks over her shoulder and lugged her Dell desktop computer out of the back of her Mini Cooper – affectionately called Minnie by her gorgeous rich blonde roommate Katrina – to haul it inside the sleek glass doors of Silver Enterprises Xpress.

S.E.X.

Annabella rolled her eyes – and sprawled onto her perfectly heart-shaped rear end when the door suddenly opened. Cradling her beloved Inspiron to her perfectly round breasts, she tried to catch her breath, only to lose it all over again when the most perfectly perfect male hand reached out to help her. Staring at the large palm, the extra long fingers, Annabella had to remind herself to breathe.

Breathe, Annabella.

The hand, Annabella discovered when she finally looked up, was attached – as hands are wont to do – to the most outrageously gorgeous man she’d ever seen. He was tall. He was muscular. He was obviously rich since he wore a diamond ring on his thumb – his thumb! How sexy.

“Miss?”

His voice – it was like honey. Or velvet. Or silk. Or silky velvety honey. Or something. It washed over her and Annabella had to remind herself to breathe.

Breathe, Annabella.

She drew in a big ol’ helping of air and sighed happily. He smelled as good as he looked. Not like that guy on the bus that time, the one that smelled like an old cigarette butt that had grown armpit hair. She shivered and thrust her Inspiron into his outstretched hand – the one with the long fingers.

With one hand, he lifted it and took it to the silver table in the center of the shop, running his long fingers over its lines and curves.

“What’s the problem?”

Annabella swallowed. Hard. “Um. It’s not doing what I say. I have an appointment with Mr. Silver to take a look at it.” She climbed back to her feet.

Two gorgeous grey eyes snapped to hers but only one eyebrow lifted. How could he do that, she wondered? She tried to raise only one of her eyebrows but both went up.

“Have you tried saying ‘Please’?”

“Yes, of course but it still doesn’t obey.”

His lips curled up in a wicked grin. “And… obeying… is something you want? Something you… need.”

“It’s a computer, so yes, obeying my commands is important.” Where was he going with this? Annabella wondered.

“So… you like having… control.”

Annabella blinked up at him because he was tall. “It’s a computer, so yes, I like to be able to control it. Can you tell Mr. Silver I’m here?”

“I’m Duarte Silver.”

Duarte. Annabella repeated his name a few times silently. It sounded sexy even in her mind. Which was funny, since her mind was usually not the least bit sexy.

At least, that’s what all the guys always told her.

“I’m Annabella Heron.”

“Yes, I know.”

How could he know her name? Annabella stared blankly until he smirked and pointed to her perfectly round breasts.

“It says so right there.”

She looked down and saw her name tag pinned to her shirt. His long fingers slid under her chin, lifted it and she was pinned by his steely gray eyes.  “Trust me?” He smirked down at her.

Dumbly, she nodded. How could she not trust him? Sure, she’d only met him a second ago, but he was tall. And muscular. And had a diamond thumb ring. And really long fingers. Of course she’d trust him. With her life.

With a triumphant grin, he whipped a tool from his pocket and she gasped. “What…what are you going to do with that?”

“Why, Miss Heron… I’m going to give you exactly what you want. What you need. Total control. Now. Come here.”

Annabella bit her lip, gulped, and then coughed for several minutes. She reminded herself never to do both at the same time again.

Never try to bite your lip and swallow at the same time again, Annabella.  

“Take this.” He ordered.

“What….what is it?”

“It’s a cable. I want you to grasp it…firmly… and give it a tug.”

“I…I…I’ve never done this before.” She stammered.

“That’s okay. I have.” He grinned wickedly because wicked grins were apparently all he knew how to do. His hands with their extra long fingers guided hers to the USB port on the rear of her desktop and… pulled.

Hard.

Annabella felt the connection break.

He took her mouse and placed it belly up on the long silver table. With the tool from his pocket, he ran the tip along the cover that restrained the ball. With a flick of his hand, the cover was gone and the ball… exposed.

“Hold out your hand.” He ordered commandingly.

Annabella obeyed. He dropped the ball into her palm. She rolled it between her fingers. Too bad they weren’t long like his.

“That’s it. Now… blow.”

“What?” Annabella gasped.

“The dust. Blow the dust off the ball.”

Dust. Right.

Annabella puckered her lips into a pout and blew. Dust got in her eyes and she blinked while Duarte Silver put the ball back into the mouse and replaced the cover.

“All done. Control is…  yours.” 

MM MM Good! Confluence, Tech Comm, Chocolate by Sarah Maddox

I bought this book by Sarah Maddox of Atlassian to aid me in my new role as leader of a social collaboration task force. Our assignment? Define the best practices for engaging our users via the various social networks that exist – a wiki being just one of them. My team at CA Technologies is in the midst of a technical information renovation – a mission to transform our content from ‘just there if you need it’ to engaging, collaborative and highly useful. We’re a geographically dispersed team working with developers around the world. We also have a large product portfolio to document so, as you can well imagine, anything that can foster collaboration around the clock is a good thing for us.
When I unwrapped Sarah’s book, I was a bit concerned by its size – it looks like a textbook. That concern was quickly set aside as soon as I opened it. On the very first page is a welcome graphic of a girl holding a tray of chocolates. “Hallo and welcome to Confluence, Tech Comm, Chocolate.”

Yes, chocolates. Oh, Sarah, you sly minx. You had me at “Hallo.”

A quick skim of the table of contents told me this book was EXACTLY what I needed to help direct my task force’s efforts. There is a metric ton of wiki advice online as well as books that describe how to configure one, how to use one, how to manage one – but almost NO information on doing so specifically for technical communicators. Right on page 4 – “Getting passionate about technical communication and wikis”  — This is my world. This is what I need to know. Now, admittedly, this book is about one specific wiki (Confluence), but that’s okay. Even if you’re using some other wiki, Sarah’s advice and insight can still help you.

Why? Because she’s a tech-comm pro who is practicing what she preaches. She truly gets the challenges we all face – i.e., finding SME time, juggling multiple priorities, managing meetings, handling issues, fitting into an Agile development environment, etc. Better, she offers practical guidelines for meeting all these challenges in ways that promote technical communicators as valued members of the product team. In a refreshingly honest voice, Sarah addresses all the daily minutiae of administering the wiki – she explains how to manage broken links, how to organize content, incorporate review cycles into the workflow, how to address legal matters like IP protection and even answers if it’s safe to allow readers to update content (“It depends.”). There’s an entire chapter on engaging readers via social media (just what I needed!) that also includes a ‘what’s in it for me’ benefits description useful for winning critical internal support.

You’re probably asking yourself if there’s really chocolate in this book. Yes, I’m happy to report, there is. Chocolate trivia facts are ingeniously interspersed throughout the book, plus a mouth-watering recipe for Kay’s Chocolate Cake is provided over several chapters. I’d been delaying this review until I’d had a chance to also try out the recipe but with a book release of my own coming up, I decided that would have to wait.

As you can see, this book was an absolute pleasure to read from beginning to end.

MM MM Good! Confluence, Tech Comm, Chocolate by Sarah Maddox

I bought this book by Sarah Maddox of Atlassian to aid me in my new role as leader of a social collaboration task force. Our assignment? Define the best practices for engaging our users via the various social networks that exist – a wiki being just one of them. My team at CA Technologies is in the midst of a technical information renovation – a mission to transform our content from ‘just there if you need it’ to engaging, collaborative and highly useful. We’re a geographically dispersed team working with developers around the world. We also have a large product portfolio to document so, as you can well imagine, anything that can foster collaboration around the clock is a good thing for us.

When I unwrapped Sarah’s book, I was a bit concerned by its size – it looks like a textbook. That concern was quickly set aside as soon as I opened it. On the very first page is a welcome graphic of a girl holding a tray of chocolates. “Hallo and welcome to Confluence, Tech Comm, Chocolate.”

Yes, chocolates. Oh, Sarah, you sly minx. You had me at “Hallo.”

A quick skim of the table of contents told me this book was EXACTLY what I needed to help direct my task force’s efforts. There is a metric ton of wiki advice online as well as books that describe how to configure one, how to use one, how to manage one – but almost NO information on doing so specifically for technical communicators. Right on page 4 – “Getting passionate about technical communication and wikis”  — This is my world. This is what I need to know. Now, admittedly, this book is about one specific wiki (Confluence), but that’s okay. Even if you’re using some other wiki, Sarah’s advice and insight can still help you.

Why? Because she’s a tech-comm pro who is practicing what she preaches. She truly gets the challenges we all face – i.e., finding SME time, juggling multiple priorities, managing meetings, handling issues, fitting into an Agile development environment, etc. Better, she offers practical guidelines for meeting all these challenges in ways that promote technical communicators as valued members of the product team. In a refreshingly honest voice, Sarah addresses all the daily minutiae of administering the wiki – she explains how to manage broken links, how to organize content, incorporate review cycles into the workflow, how to address legal matters like IP protection and even answers if it’s safe to allow readers to update content (“It depends.”). There’s an entire chapter on engaging readers via social media (just what I needed!) that also includes a ‘what’s in it for me’ benefits description useful for winning critical internal support.

You’re probably asking yourself if there’s really chocolate in this book. Yes, I’m happy to report, there is. Chocolate trivia facts are ingeniously interspersed throughout the book, plus a mouth-watering recipe for Kay’s Chocolate Cake is provided over several chapters. I’d been delaying this review until I’d had a chance to also try out the recipe but with a book release of my own coming up, I decided that would have to wait.

As you can see, this book was an absolute pleasure to read from beginning to end. 

The Adventure Continues…

Not so long ago, in a galaxy on an island not so far away, a technical writer faced a horrible truth…

Her development team did not like working with her because, they said, “…the content she delivered was always wrong.”

First, she got mad and tried to explain that she was working without a thorough understanding of the product’s benefits, and in many cases, working without access to the product (!). She was developing procedures based off requirements documents created for various gate reviews and her only means of communication with her team was email. No one told her things had changed since those documents were written, even though she sent her work out for review. Instead, they pushed her out of the loop and just wrote their own content.

True story.

January, the time of year when everything is new again, marks a number of organizational changes. New job roles, a new technical information process that had to fit into a new agile software development process, new team members, new bosses, everything’s new, NEW, NEW! For some people, this much change produces anxiety, but I am embracing them like another New Year’s Eve party.

As of a few days ago, I am now an Information Engineer. While I’m sad to see Technical Writer go the way of the dinosaur, I love the new moniker because it better explains how my role has changed I’ve kept up with the changes in this field.

This is a key point: I don’t think we can afford to wait for others to hold our hands and tug us to the next level. We must drive Technical Communication beyond the confines of the user manual. This means taking responsibility for learning new tools, following technology trends, taking risks.

When I first began working in this field, I remember hating to ask questions, afraid the perception I was creating was one of someone who didn’t know her job. Today, I consider this the number one tip on a What Not To Do list. I now ask questions constantly – it’s how how I learn. The answers to the questions I ask frequently take my thought processes into new directions – directions I would not have taken on my own. Asking questions is THE most important thing I do each day.

This is handy because one of the changes my employer is making is an ambitious initiative to completely transform technical information. We’re not writing manuals anymore. Instead, we’re writing very specific and focused scenarios – think articles – that include just enough information for users to solve a particular problem. Articles align with an Agile project’s user stories and can be ported into any number of information sets including books, Wikis, Help Systems, etc.

Sounds easy, right?

That’s what I thought.

In practice, identifying the content to include in an article has proven extremely frustrating for a number of reasons:

• My brain is stuck in book-mode. I figure it’s going to take my brain a while to stop thinking linearly. I must consciously think of what information a user needs to solve the problem at hand and no more.
• Agile user stories don’t neatly align to my work. This, I believe, is a growing pain. Frequently, the user stories the development team writes are way too granular for my work and are better suited as steps in a procedure, which in turn, may be part of my ‘article’.  I then thought I should try to map all the Agile user stories to the appropriate tech info article, but found many of them have no technical information impact. For example, back-end coding requires tracking so a developer creates a user story for it, but there is no corresponding UI function. It’s entirely code-based and automatic. I now focus on only the user stories with a UI function.
• My work crosses over sprints. I planned to document the user stories in lock step with the code developed in any given sprint. This has been working well for developing outlines but not for review-ready drafts. Again, I suspect this is a growing pain that will resolve itself as the development team gains expertise using Agile methodologies. So, for Feature X, I may be able to document only Adding X in Sprint 1, Deleting X in Sprint 2, and Modifying X in Sprint 3. This is perfectly fine, but it taxes a brain (see bullet 1) still stuck in Book Mode that wants to document the entire feature.

All these frustrations had me convinced I’d be hearing a sequel to the sad story I shared above. Instead, something cool has come out of it. During a conference call with my product manager this morning, we were exploring a new software tool the team is adopting for Agile tracking purposes. The tool was slow, subject to frequent hanging and eventually crashed. To fill the wait times, he brought up some concerns with various technologies and how they could impact our development efforts. To my astonishment and his, I not only knew his concerns, I understood and could contribute to the discussion.

This is a significant achievement – we’re only a few months into this project. For me to have this level of depth so early into the process is nothing short of miraculous. He pointed out that the team is now ASKING me questions instead of simply copying me on emails.

And this is only the beginning. I’m excited to see how an entire project developed and delivered using our new processes will be received by our customers.

What changes are you facing this year? Do they excite or terrify you? 

Adventures in Scenario-Based Documentation

Back in June, I posted about a new initiative my technical writing team planned to adopt. It’s called Scenario-Based Content, a strategy that fits our work as technical communicators into the abbreviated schedules typical in an Agile project.

If you read the June post, you’ll remember I was perplexed by the idea. I wasn’t sure how Scenario-Based Content was any different from the task-based content we were already developing.

In the time since June, we’ve had some training and opportunity to practice during a certification process, which I just completed today. My impression? Scenario-Based Content just may be the answer to several questions.

How are Scenarios Different from Tasks?

Scenarios should align with user stories. For example, “I want to recover my protected server from a disaster even though I don’t have the disaster recovery option.”

This user story was my certification project. The solution to recovering this server is not a single task. Rather, it is about ten tasks, about half of which are optional, depending on outcomes of prior tasks, as well as on the specific configuration of the environment where the disaster occurred. All of these tasks were already written and included in our product’s Admin Guide. But we never addressed how users might actually read those tasks or we’d have know how difficult they were to follow.

I took apart the monster section and organized it into baby tasks. My first requirement for certification was to design a flow chart that explains the scenario. This, as it turns out, was crucial for my own understanding of the process.

The process, as originally written, had so many conditions, I kept losing my place. Distilling it down to something that could be expressed by a standard diamond decision shape required nesting conditions, which in turn, showed me where to break out the various optional procedures.

Armed with a list of baby procedures, it occurred to me that I needed a mechanism for guiding readers back to the main path through the flow chart. I added a What Should I Do Next section to every task in the scenario.

Can Scenario Documentation Truly Fit Inside an Agile Cycle? 

I was skeptical about this until I tried it for myself. At the same time I was practicing for my certification, I was also assigned to a new product team. This new product has several sprints already scheduled. I read the user stories planned for each sprint and began setting up scenario content shells ( I don’t have a working UI yet). Right now, I have three major scenario shells, which I may further break down, once I see how complex the UI is that supports them.

What astonished me was how much of this new product I already understand and it was just kicked off. With our old process, I wouldn’t have reached this point until several months into the year-long production cycle.

Will Scenarios Document the Whole System?

In a comment left after my June post, “Techquestioner” said scenarios may not show you the whole system. I think this is true to a large extent but hasten to add I don’t think that’s necessarily a bad thing.

Here’s why:

The Admin Guide for one of my products is nearly a thousand pages. How frequently do technical communicators lament the fact that no one is reading our work? This is due primarily to our insistence that every detail be covered. The problem with that approach is most people will never have need for all of those details. For example, my product works on all Windows operating systems dating back to XP. But if some users are running Windows 7, they have no need for all the XP details.

Sure, we could debate publishing baby books for each OS version over the merits of single-sourcing, but the point remains the same – we’re giving them too much information.

Scenario-Based Documentation focuses ONLY on the information needed to solve the problem described in a very specific user story. If there are twenty fields on a UI dialog, but only three of them are needed in a particular scenario, then only those three are documented. The balance will be documented in some other scenario until, eventually, all fields are documented.

Aren’t We Doing Double Work? 

Got me there. Here’s one problem with Scenario-Based Content: Help Systems are still UI-centric. If I click a Help button on a screen, it means I need help on that screen. I don’t want to have to click through a dozen scenarios until I find the one that contains the instructions for completing the one field I need.

So I still see us documenting software screens separately for Context-Sensitive Help systems in addition to Scenario-Based Content development.

Based on what I’ve practiced and applied so far, I like the Scenario-Based Content approach.

How are you documenting software in Agile environments? How are you addressing the problem of fitting UI-centric Help screens into a scenario-based model of development? 

Information They Can Really Use

My technical writing team recently unveiled Scenario-Based Content, a new documentation strategy that aligns with the same sort of use cases documented as part of an Agile project.

That’s the theory, at least.

My introduction to this new process left me scratching my head. How is scenario-based content different from what we’re already doing?  We’re writing tasks, not concepts, so I had difficulty imagining how I’d apply the new initiative to my work. We had several more presentations and finally, I spoke directly to a writer on a different product who’d already begun using the process.

But it wasn’t until Tom Johnson posted this essay on the failures of topic-based authoring that it all made more sense. As Tom notes:

“The problem with topic-based authoring is that many times, these tasks don’t mean a whole lot in isolation.”

That statement reminded me of my experiences teaching SAP a few years back. When we pilot-tested a course I’d written to teach users how to create product codes in the new system, we discovered all the course did was present a series of isolated tasks, one after the other, with no backbone to tie them all together. Because the SAP system was quite different from the legacy system it replaced, the new tasks did not align perfectly with old ones, so even users’ domain knowledge did not help them. We ended the pilot early and redesigned the course with the end-to-end scenario superstructure Tom describes.

I sat with the students themselves as well as the SAP development team and produced job aids, process flow charts, and various cheat sheets that were essentially a bread-crumb trail through various use cases. For example, the use case for Create a Sellable Product Code is NOT identical to Create a Component Code. Creating a sellable product code required users to perform at least five different SAP tasks, including creating component codes. Worse, those tasks had to be performed in reverse order when compared to the legacy system. The end result was a well-trained user group able to successfully create product codes.

If you’re wondering why I did not design the course this way from the beginning, you’re not alone. The answer? We thought we’d covered that during design. The SAP implementation team consisted of actual business users, yet even they did not consider tying together the tasks required to achieve some goal. Every one believed it would be obvious to users when just the opposite turned out to be true.

This is a problem quite typical on project teams where schedules are aggressive and access to the right experts is scarce. As we adopt our new scenario-based content strategy, I’m concerned the same fate will afflict our documentation.  We don’t always have access to real users and must rely on internal experts from Support, Development and Education.

I’m still not sure how to actually apply our new content strategy but I do think it has the potential for making our information truly usable. What do you think about scenario-based documentation?

To the Help/Doc 2.0 Future… and Beyond!

Scott Abel, known as The Content Wrangler in technical communication circles, published a fantastic piece in April’s Intercom called The Future of Technical Communication is Socially Enabled: Understanding the Help 2.0 Revolution. I read the article, nodding in violent agreement at each point Scott made. Last month, I presented a similar vision to my colleagues except I called mine Doc 2.0. Surprisingly, the feedback I received from that event is trending toward push-back rather than acceptance. “I’m busy just writing the content. How will I find the time to learn new technologies, deliver content in new formats, or keep up with all that tweeting?”

Scott promises to address the skills we’ll all need to succeed in a Help 2.0 socially enabled world in a later issue of Intercom. But I wonder if we can give him some first-hand accounts now – what are YOU doing to stay on top of this emerging trend? Do you agree with us – is a socially enabled Help site the future of tech comm? How do you change the minds of those who (still) think PDFs are just fine?

Incorporating Video into Technical Information

I’ve earned sort of a cool reputation among my colleagues as “Patty Spielberg” for all the work I’ve done on our product demo videos.  (They’re posted up on YouTube if you’d like to check them out.)

As cool as this is, there are also some drawbacks to it, tops on the list being I DO HAVE OTHER WORK TO DO!  Video production has a tendency to suffer Scope Creep, so here are some tips on managing this effort in case you find yourself in my predicament.

Invite Murphy

Don’t even try to prevent things from going wrong; they will.  It’s a given. The best prevention is to have contingencies in place.  We’re using Adobe Captivate to produce our videos, but not all writers have a license and running it from a server is prohibited by the license terms.  So, we installed it on a lab machine we can all use. Sort of like a kiosk. This is the backup plan in case the version I have on my laptop fails. I also have a backup mic in case the primary mic fails.

Set up the Environment

Documenting software without a functional version to play with is challenging, certainly not a best practice, but nevertheless, doable. But producing videos without a functional version is just not possible.  For this reason, I defer video production to as late in the development cycle as possible – usually, right before beta begins. Of course, waiting this long risks meeting the project schedule, so you’ll have to weigh those risks over the potential benefits, such as recording from a stable and (hopefully) bug-free software build.

You should also have a thorough understanding of the task you plan to record. I’m doing product videos for all of my team’s products, even those I’m not documenting. Because I’m unfamiliar with the interface and the design intention, I frequently cannot perform a task without expert guidance.  When you plan a video production project, remember to plan for some practice time. Familiarize yourself with all the menu selections and values that should be entered in selected fields so that you can perform the entire task without error at recording time.

Measure Twice, Cut Once

I like to work with a script for this reason. If I am not the technical writer assigned to the product I must video, my first step is to study the tech writer’s content. Much like peer editing, I often discover ambiguity in procedures as written by lending fresh eyeballs. I use the written procedure to develop a script. My scripts are Word tables with two columns: one for a description of the on-screen action including what screen should be displayed, what menu to select, what values to enter.  In the second column, I add the voiceover I plan to record on that screen.

I route all video scripts for review and approval within the product team. Members help me use the best terms (“Use ‘recover’ not ‘restore’), identify inaccuracies, offer suggestions for the features they want me to emphasize.  Script approval before the work begins is a critical time-saver. Once a video has been recorded and sync’d, changing problems after-the-fact requires an almost total re-do.

A Lot of Cooks in the Kitchen

As our video demos gained traction, they’ve evolved according to various corporate directives. For example, my first attempts merely had our company logo. Today, the Marketing team asks that I use a specific PowerPoint template for branding purposes, and a Flash fanfare opening sequence. There are also copyright and legal disclaimers I must use.

The Localization team is busy working on a way to streamline the translation process without having to completely record a video in each language. Depending on the size of your company, there may be additional teams with a stake in each video, i.e., Education, Pre-Sales, etc.  Track each requirement carefully and be sure to estimate it in future project plans.

Ask for Help

This aligns with that pest, Murphy, and his annoying tendency to foul things up. Since we’re deferring video production to as late in the development cycle as possible, time is naturally not to be wasted. Yet, like most people, I typically have more than one task on my daily To-Do list and those things cannot always wait until a video is done.  It’s okay to ask for help. During my latest video production efforts, I had a product with no name, an unstable build, a laptop that went on strike, a personal situation that required three days off and an injury that caused some discomfort to contend with.

While my laptop was being repaired, I worked on the kiosk. I revised the script so that the product is named as infrequently as possible, used photo-editing software to change the screens where instability was visible and took frequent breaks to help manage my pain. My colleagues helped record software tasks and prepared one of my other projects for a localization turnover while I locked myself in an empty office to record the voiceover. I could not have succeeded without the assist.

Give Them Food or Teach Them to Fish

Finally, I suggest documenting your own procedures as you fine-tune them and then holding impromptu training sessions with your colleagues. I did just this last month, so when I asked my coworkers to record tasks using Captivate, they were capable of doing so with minimal guidance from me. Not everyone is comfortable recording narration, though. Honestly, I’m STILL not comfortable with it myself.

That’s pretty much it. As writers emerge from their comfort zones and begin learning multimedia technologies like screen capture and video production, this will become as easy as typing. Tell me, are you incorporating new media into your documentation projects? I’d like to hear about it.

A technical communicator’s history lesson

Last week, Tom Johnson posted twice about how users read (Less Text, Please and Making Help Content Enjoyable to Read – Impossible Quest?) The blog posts and resulting conversation that took place via the Comments proved the argument that people read differently according to their goal.

This got me thinking.

At first, I skimmed the posts, believing that we’re already addressing this by organizing content according to audience roles – for example, offering an Administrator’s Guide in addition to an End User’s Guide, because the two roles use the software differently.  But as I read more deeply – and this is a point I will revisit later – I realized that “use” of content shouldn’t be confined to job role. Within and across job roles, users read for different purposes – Doing, Learning, or Learning to Do. (Read the posts for more information on these concepts, as well as their sources.)

This reminded me of my first job back in my early twenties. Between 1987 and 1993, I was a secretary at a large commerical bakery whose products are sold in grocery stores. Managing the bakery’s large fleet of delivery trucks required access to data like mileage, fuel consumption, maintenance history, parts usage, and accident reports. The fleet was geographically distributed over most of the northeast so collecting and analyzing all of this data would have taken weeks if we hadn’t been able to computerize it.

Back then, we didn’t have Windows or email. There wasn’t even an Internet yet, not as we know it. We used a network of PCs running an operating system you probably never heard of: B.O.S.  Business Operating Systems. It was ugly; no fancy GUI screens, just old fashioned Green Screen. Everything was command-driven. All these years later, all I remember is the $ prompt. $A, $F, $S. I had a list of these $ commands typed in a single skinny column taped to my monitor.

My first Quick Reference Guide. (grin)

As I noted in my comment on Tom’s blog, I was asked to produce a monthly report from this system. There was a report generator called Auto Clerk that could produce reports from the database. I was handed an Auto Clerk guide, a Command Reference Guide, and a third guide whose name I can no longer remember that was mostly concepts and explanations.

I had a goal in mind – produce a report. That’s all I knew.  In other words, I did not know what I did not know to achieve my goal. The index and table of contents contained technical terms so I could not look up anything unless I first “spoke the language.”

That must be what the unnamed third guide was for. I read it cover to cover. I learned how long BOS existed, how it worked, what technologies it was based on. I finally found a very high-level description of the report generation process. That sent me to the Auto Clerk guide.

Again, I had to read the entire book cover to cover simply to learn what the right terms were in order to achieve my goal. What $ command instructs the system to first query the database and then display or print the results of my report design.

Wait. What report design?

Okay. Back to formula. I then focused on finding the commands to design a report. First, column layout, then the fields in the database whose values would provide the rows of the report.

That brought me to the last book, the micro-COBOL command reference guide where I had to find the commands and the syntax that would produce the output I wanted.

This took me almost two months to do. Granted, that was in addition to my usual responsibilities but still, two months of research? After two minutes of clicking links, I am now frustrated.

When I finally got a report out of that system, I typed up the entire procedure in my own words. I didn’t know it then, but that was my first piece of true technical communication.

What have I learned from this?

• BOS assumed I was reading to learn. I was not. I was reading to do.
• BOS presumed I already possessed a certain level of technical proficiency. I didn’t. I hadn’t yet finished my college degrees. However, I can tell you this – producing the report did NOT require all that domain knowledge.
• The Table of Contents and Index were not designed to help me find information; they were designed to browse for information. In other words, you must already know what you’re looking for.
• The guides were missing any real, specific examples, expressed as a typical user need. I had to cobble together syntax examples provided at the bottom of each command description in order to string together the combination of results I needed. The challenge with this is the technical writers used < > to denote user-specified values. I had a devil of a time determining when to omit those brackets in my own commands and when they were required.

How Would I Have Done This Today?

So much has changed since my days dealing with BOS. I would speak English instead of COBOL or whatever geek-speak a subject requires. For example, instead of writing a heading like “$F Command – Report Generation”  – a heading that told me nothing about its contents, I would have written, “Design Your Report’s Layout”, “Specify the Data to Use in Your Report” and “Display or Print Your Report.”

Adobe similarly frustrated me with headings like “Use the Dodge/Burn Tool.”  That would be great if I already knew what dodge and burn mean.

In the Index, I would enter such a topic in English, for those who don’t yet have the domain knowledge, and in geek-speak, for those who know what they’re looking for.

I’d make use of hyper-text technology and demote all the high-level conceptual stuff that did not matter to me in my goal of producing a report to an exandable link in a Help system – there if I want it, not there if I don’t. Deep Reading, the kind of reading I do when I read a novel, for example, or study a textbook, requires the proper mind-set. I cannot put myself in Deep Reading mode when I know I have a conference call in fifteen minutes, two people are at my desk, and my Inbox has 400 unread messages.

I would organize the commands by purpose not alphabetically. The Index is already an alphabetized list. I’d provide tons of real-world problems with the exact syntax for solving each.

Uh Oh

My shoulda/woulda/coulda list got me thinking. Am I doing all this today?  Sort of. On one of my projects, I added a nice What Would You Like to Do Next section to most of my help topics, which achieves a few goals. First, it gives readers a sense of direction. “I’m here and want to go there.” Second, it conveys sequence. “I’ve done X and Y and still need to do Z.”  It implies ordinance. “I’ve done X; now I can do Y.”

But I could do more. Sadly, I find so much of my ideals are sacrificed to the gods of project schedules and budgets.

So, that’s how Tom’s posts got me linking my past to my present. What do you do to address not just different audiences, but different ways of reading in your technical writing?