To the Help/Doc 2.0 Future… and Beyond!

April 27, 2011

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

March 18, 2011

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

January 28, 2011

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?


Kinect GUI: Now “Gesture” User Interface

December 27, 2010

On Monday following the Christmas holiday, I decided to work from home due to a blizzard that buried my area. I spent the morning editing the UI for a new app my team is developing. Menus, on-screen instruction, error and warning messages all need to meet certain requirements while also providing exactly what users require to operate the software tool.

After several hours of editing, I was ready for a break. My sons gave me Microsoft’s new Kinect sensor for the Xbox game system and a Zumba game. Since I take a weekly Zumba class, I decided to give it a shot. I stood in the center of my living room with the Kinect sensor placed on top of my TV, directly in front of me. On-screen prompts were easy to follow. I only had to wave at the sensor and it detected my presence. I did a forty-minute Zumba workout and discovered, to my delight, that I did not have to exaggerate any movements or perform any complicated hand gestures in order to control the system. I had a great deal of fun with it and forgot I was playing a game.

Until I decided to stop.

I discovered stopping the game wasn’t so intuitive. There was no on-screen control for me to wave at. It took several minutes and then my son remembered the gesture for Stop. I think it was holding my right hand down and my left hand up at a 45-degree angle. In other words, users must memorize the Stop gesture.

Once I stopped the game and caught my breath, I started thinking. Have we, at long last, finally evolved past the Window and mouse as user interface and made the stuff of science fiction a reality? In Iron Man 2, Robert Downy, Jr. brings his hands together in a single clap and then pulls them apart to manipulate a 3D view of a map. In author Jeff Somers’ Avery Cates series, most of the technology in Cates’ world is operated by gesture. The iPad for example, employs a sort of pressure/gesture hybrid action to control it. Use a modified “tickle” gesture to turn pages and a two-finger pinch to minimize windows. Kinect employs a simple hand wave gesture to first control an on-screen cursor and then to play a game designed around natural body motion.

When software was anchored to a particular hard drive, it had to adhere to the standards established by the operating system. But as we reach for the Cloud to lease software, these standards no longer apply. Applications can now evolve past Windows and mouse-clicks in favor of more intuitive commands, based on the gesture.  The UI editing work I did this morning reminds me how important it is for the interface itself to provide useful information. While trying to stop my Zumba game, I looked for on-screen controls to wave at, but found none.  I wonder how a Gesture User Interface like Kinect could be adapted for basic office use, such as word processing?

What do you think about GUI evolution?



Cloudy Forecast for Tech-comm?

October 14, 2010

As my employer looks to tap into the cloud market, I’ve been doing cloud-related research to gain perspective on how my role will evolve to support cloud initiatives. The predictions are staggering and the implications for tech comm, a bit nerve-wracking.

According to Gartner, 20% of businesses will own no IT assets by 2010. This doesn’t mean companies won’t need IT at all but does mean they’ll look to the cloud to lease services, equipment and software.   I like to compare this trend to the operation of a car.  How many of us have a driver’s license? How many licensed drivers understand how the car’s various systems work?  How many drivers can repair their car?   The shift toward non-ownership indicates businesses would rather pay for the benefits of IT without also having to care and feed it.

Also according to Gartner, context will be as influential to mobile consumer devices as search engines are to the web by 2015. While search engines pulled content from the web, context-enriched services will push information to users based on analysis of patterns. We’re already seeing this with Amazon’s book recommendations.  I think taxonomies and tagging will require more intent than content development itself.

This segues neatly into the next prediction, that by 2013, mobile phones will pass PCs as the most common device used to access the web, worldwide. As Gartner points out, users expect fewer clicks on mobile devices than on PCs but I also anticipate renewed vigor toward minimal content.  Windows is nearly twenty years old; I think we can now safely drop mouse-related terms like click, choose, and select from procedures, similar to this example posted by Julie Norris.  With this approach, content would be faster to develop, less expensive to translate, and easier to port to mobile devices.

These predictions make me wonder where our efforts will take place. Will tech-comm be outsourced to even greater degrees than we’re already seeing? What impact do you think shrinking IT staffs and budgets, and the commoditization of IT will have on tech-comm?


Out of my comfort zone

October 11, 2010

An amazing thing has been slowly taking place in a virtual world and I almost didn’t notice. Okay, I actually just noticed it today.  If you follow me, you probably know some of my history – that I didn’t know what Twitter was a year ago.  Today, I have two accounts (you can follow @pattyblount2 for tech-comm or @pattyblount for personal interests which are: chocolate, my sons and fiction – writing and reading it.)

What you may not know about me is that I am – or maybe was is the appropriate verb – an introvert at heart. Growing up, I was the girl hiding in the shadows, her face pressed in a book.  Kids stole my toys, took my turns, took credit for my ideas because I never spoke up. When I grew up and went to work, it was more of the same thing as others got the raises and promotions that should have been mine.  I was doing great work but yet, wasn’t getting noticed.

As I got older, I learned speaking up is a critical business skill.  I took some Dale Carnegie courses (which are amazing and highly recommended). I got better at it but I’m still not entirely comfortable with it.

Meanwhile, a trend started on the internet. It began with lists, like TECHWR-L, morphed into blogs and social networks. Professional wisdom, experience, opinion and even disagreement – all collected and focused in a single point in time.  I cut my teeth on TECHWR-L, lurking and reading every message with great interest. Members of that list taught me how to be a technical writer.  But I rarely posted or replied to posts. I always thought I had no wisdom or experience to share.

Over the years since I began in this field, I have (I hope!) collected enough experiences to form opinions – wise or other-wise (ha!).  With Twitter, Facebook, LinkedIn and our various blogs, it’s become easier for me to express them. I comment on subjects in which I have experience, ask questions on those I don’t, connect with other professionals who continue to teach me and shape the information products I deliver. It’s a subtle thing but I’ve suddenly realized I have an abundance of confidence as a result of my connections to all of you.  I noticed it to last week during a meeting to discuss content strategy for a new product offering. My heart was not pounding. I was not sitting in dread, waiting for the moment where I would have to share. I was calm, interested, expressed my opinions and the world didn’t fall off its axis.

I am enjoying an unexpected benefit of social networking – confidence. Thank you all.


Where’s the forest?

August 24, 2010

Over on LinkedIn, the Agile Tech Writers group has been helping me deal with one of the biggest challenges Agile Development has presented so far – how do you document an entire software product when sprints are merely a small glimpse of the big picture?

We’re still getting our feet wet with Agile, but I have one project that is a brand new product, which I’ll call X here.  In our old development process, X would have a series of requirements documents for each feature, plus a master requirements document that I would use as my base.  The descriptions in these docs provide a starting point for my external research (our products support other third-party apps), which in turn help me develop the right questions to ask to fully document the new system. But in our current Agile process, I have no requirements. All I have now is an entry in a sprint back log for one of the Product X features.  I’m supposed to be documenting this feature with no idea how it fits into the product. I know there is a forest out there, but I am stuck on one branch of one tree.

Where do I begin? I am essentially writing inside out. How can I fully document a feature during a sprint when the rest of the product is still being developed?

Based on the comments received from the Agile Tech Writers LinkedIn Group, the problem, it seems, isn’t with my process, but may be with me.  I’m still trying to work the same way I’ve always worked while Agile has changed that model. The questions I used to ask my development team no longer apply. From David Farbey, I learned instead of asking very specific questions regarding the feature’s use, I should be asking questions geared toward understanding its implementation and the advantages it provides to users.

In a comment from Chris D., who said Agile opens doors, I realized it’s no longer enough to sit and wait for information to trickle down to me. Nor must I track it down. Rather, I should be getting involved in the development effort, looking for places to influence interface design and being what technical communicators have always tried to be – “a true customer advocate.” Anne Gentle wrote in a recent post that “Being an active member of the Agile team is crucial to a writer’s success.”

Toward this end, I contacted the Product X Development team and asked when their scrum meetings take place. I’ll show up, listen while looking for places where I can add to the discussion, even though it may be too early in the process, at least from a traditional perspective. But my confidence is returning. I have a UI background, so I can certainly influence decisions there.

David F. also reminded me of a key point in Agile development: “Developers do not code an entire product release in a sprint.”  Yet, here I am, trying to document all of Product X during a single feature sprint. Ideally, the information I write for this feature would be modular and ready for integration into the full product doc set at some later date. It’s okay if I don’t have the whole picture now. It’s even okay that I state during scrum meetings that I can produce only X-related conceptual topics during this sprint.

The point, I have learned (thanks to Sara, Julio, Pat, David, Kat, Maya, Verner, Larry, Chris, and Pramod), is that Agile can be flexible and therefore, so should I.