From the Doc Side : technical communication

Twitter - Can it Make You a Better Technical Writer?

Steve Pham — Thu, 16 Apr 2009 18:19:00 GMT

Copyblogger's Jennifer Blanchard thinks so and I completely agree. According to the post "How Twitter Makes You A Better Writer", Twitter helps writers in three ways:

Twitter forces you to be concise.
Twitter forces you to exercise your vocabulary.
Twitter forces you to improve your editing skills.

Being fairly new to Twitter, I find myself constantly editing my tweets (the Twitter word for posts) to fit the 140 character limit. Because of this limit, you do have to be careful about what and how you choose to write your messages.

How does Twitter force you to be concise?
There is no getting around being brief. You write more than 140 characters, your message doesn't get sent. You learn fast, capture the gist of what you want to say, and quickly send it out.

Why do you need to exercise your vocabulary?
If you only have 140 characters and have to be concise, you want to choose the most effective words to get your message across without using ones you don't. So you start thinking about ways to say what you want with creative word choice and not extra sentences. Each word matters. When each word matters you think about them a lot more.

What's editing have to do with anything?
Because of being concise and evaluating each word choice, you often have to re-read your messages quite frequently to evaluate whether it's what you meant to say. But, you don't have all day to edit a tweet. Twitter forces you to write better in shorter amounts of time because a medium like this is all about being timely. The posts need to be fast yet good. You can't compromise quality just because it's a microblog. And, you want to send out good content that relfects well on the rest of your content and your skills. Editing well and quickly is of essence.

So how does this help technical writers?
Well a good portion of help authoring is to deliver information as effectively and efficiently as possible so users can get back to the task they were trying to accomplish. Technical information isn't prose or poetry. No one wants to read a book on how to turn on the computer. A tool like Twitter can make you aware of how important each word choice is but it can also teach you to get your message across sooner. As well, I find it encourages creativity in being effective. Creativity is always an important tool in staying relevant in technical communication as well as learn how to meet your users' needs with less space and words. People want help with their problem now and then to move on. Twitter is great then for teaching technical writers to focus on one problem or message and quickly move onto the next task. What do you think? Do you agree? Or, do you think tools and mediums like Twitter are ruining the English language?

Have you committed a technical writing sin?

Steve Pham — Fri, 27 Mar 2009 19:40:00 GMT

I’ve been re-reading some old posts in the field, and after reading Amy Hoy's Slash7 post on "How Tech Writing Sucks: The Five Sins," I started thinking… is it really possible not to commit any one of the five sins?

The Five Sins -

Losing the reader
Making the reader feel stupid
Failing to stick
Being a total bore
Not providing much-needed context

Hoy says the five sins are results of "bad" writing, but can you realistically prevent these things from happening for all users? As a n00bie in the field, I’m learning how to ensure the reader is getting what she needs out of the documentation. One objective of documentation is… user needs help, refer user to a guide or help file, user resolves issue on her own, and in doing so, saves user time and a phone call to customer support. Pretty simple... the objective at least seems that way, but now comes the tricky part.

How do you keep the reader engaged with relevant, lively content, without feeling stupid, so she can remember it the next time she completes the process?

Seems straight forward, but then again, we are discussing user guides and help files. These materials aren’t usually opened unless there is an issue, and then they are closed as soon as the issue is resolved. I guess what I am proposing is, these sins are sometimes inevitable. Here’s why…

You will lose the reader as soon as the issue is resolved.
No matter how you write, you’re going to make some reader feel stupid – either talking above or below them.
Most of the time, the content users are looking for is not everyday occurrences. Failing to stick is predictable and they will have to search for the answer again.
No matter how pretty you make it look, technical documentation is not going to be the most exciting type of reading available. How many manuals have ended up on the bestseller’s list?
Can you document everything? Probably not. So anytime a user cannot find something she is looking for, she is going to find it lacking.

I understand we are supposed to write in a way that best prevents this from happening, but perhaps it’s just the nature of the beast. You can’t expect to satisfy everyone can you? But I bet you can expect to commit one of these "sins.” What do you think? Can we strive for and achieve sin-free technical content? And if not, is it good enough to learn from our mistakes and keep improving as we go along?

How do you explain technical writing to a kid?

Lindsey Robbins — Tue, 24 Feb 2009 16:51:00 GMT

The short answer is… you don’t!

Last Friday, I had the distinct privilege to be part of a special field trip for kids from Meeting Street Academy (See Rachel’s blog post for more background on the special event). In short summary, I was to explain to four and five year olds what I do for a living. Hmmm… technical writing in the eyes of a child.

Here are some things I thought of… (and yes, please feel free to laugh at my feeble attempt)

Do you like to read?
What books?
Do you like to make up stories?
Do you like playing on the computer?
Add that all up and you can be me!

See in my mind, I was trying to explain how a kid their age who loved reading and stories somehow became me as an adult with this career that involves playing with things and writing about it. I even showed them the *books* we write and how they have pictures (screen captures).

I really wanted to explain how curiosity was important in my education and career but wasn't exactly sure how. However, I think in general I was supposed to show them that it’s important to read, to learn how to write, and to stay in school. I loved how they liked to raise their hands to ask questions, that’s a good sign! Being eager to learn is definitely a part of technical writing.

I’ve given plenty of talks about technical writing before (to college age kids) but this experience gave me a chance to see what I do through the eyes of a child. And, I laughed. It’s not exactly possible but I think just seeing someone who has a job they love and enjoy is important. I hope they continue to see positive examples of people who applied their learning to a cool career. If one of them happens to take on technical communication, all the cooler.

How would you explain your profession to a child?

The life of a n00b...do you smell fire?

Steve Pham — Mon, 23 Feb 2009 16:10:00 GMT

Being the new guy on the team and having limited exposure to “true” technical writing definitely makes me feel a bit intimidated especially when there are individuals with 5-10+ years of experience under their belts. Immediately, I felt as if I needed to catch up and learn about the technologies, methodologies, and any other of the “-ies” words. This fire under my uhh…seat, wasn’t due to any pressure from the team, in fact, they encouraged me to learn at my own pace and not to feel rushed to get into anything. Phew…that’s reassuring.

Well, fast forward to two weeks later, and here I am writing this post, reiterating what I had learned about being a technical writer and user assistance.

First being a technical writer:

I mean technical writer…sounds exciting doesn’t it? I am sure plenty of us grow up saying, “Daddy I want to be a technical writer when I grow up!” However, in all seriousness, it is really an interesting and diverse position. This post about Unexpected Characteristics of Technical Writing summed it up pretty well. And here is my summary of that summary:

Requires a good amount of social interaction
Skills in:

writing
graphics
troubleshooting
coding
project management
usability
etc…etc…etc…

Knowledge of the software (hopefully this is obvious)

The last bullet was my biggest reason for becoming a technical writer. I love to learn, so what better way to learn and truly understand a product/software than to write how it works? I just learned the basics of a new software tool that we use and now I am excited to use it.

Secondly, user assistance:

After reading the article, What if Readers, Can’t Read?, I was certainly intrigued on how user assistance is shifting. Mainly, because I fit his statistics (as most people my age probably do).

For instance, an average college student buys a text book worth $100, but never opened it. Wow! I thought I was the only idiot who did that…that makes me feel better.

Here are some more shocking stats:

China will soon become the number one English speaking country in the world.
One in eight couples married in the US last year met on the Internet.
The percentage of university graduates from India with English language skills is 100%.

So what does this all mean? We have to adapt to the change of times. I know we are currently doing so by updating our Online Help Files on our new Infinity Platform. We are also constantly researching and understanding the new technologies that will make our jobs more efficient and make our users happier.

As I still have a lot to learn about a lot, I hope you will follow me on my journey to understanding the challenging and changing fields of technical writing and user assistance. And, help keep that fire under my seat going. Who knows maybe you’ll notice a few sparks under yours?

Journey from Structred Frame to SharePoint Server Wiki

Lindsey Robbins — Tue, 18 Nov 2008 11:36:00 GMT

The journey from last week to this week already feels a decade long as I’ve encountered many trials and errors in converting internal team documentation authored in Structured FrameMaker into a Microsoft SharePoint Server 2007 friendly format. In other words, complex framemaker to basic html.

I’m not complaining about the trials and errors. On the contrary, it’s been exciting to dig my hands into this fun little side project that keeps evolving and building.

Well really, I need to take you back three years to get to the root of where I’m at now. It all started with two separate projects. The first started as learning about how we generate help from Adobe FrameMaker using WebWorks and my lesson was our internal documentation help file the Tech Writer Master. Sounds intimidating doesn’t it? I spent a lot of time updating, organizing, and examining the information design of the help file. Unfortunately, a problem we frequently faced was there wasn’t an easy way to quickly and efficiently update the internal documentation. And as you know, processes, workflows, and general daily work information is fluid and changes often. So I kept the internal documentation as an interest especially because of my passion for knowledge management.

Then that summer, I was tasked along with another co-worker to research how we might, and whether it was valuable, implement our help file as a wiki. We ended up going a different direction with our Infinity help but I was able to bring in my wiki experience and often ask myself what role wikis could have in user assistance content. When the wiki project ran its course, I kept up with the free wiki tools out there and wanted to find a way to install on my own machine and run as a web server for my team. I knew ultimately that having the Documentation team work on a wiki would provide valuable experience in new ways of thinking about content management.

Months went by and my company rolled out Microsoft SharePoint Server 2007 as our internal company content management system. I knew SharePoint had some wiki capabilities but I had to test it and see if it could work for us. I ended up choosing a Wiki Site from their templates. I played with it and in a matter of days, I had a team wiki set up. It wasn’t perfect, didn’t have all the features I wanted (especially around navigation), and proved frustrating at times but I was able to get the basics of what I needed up and going. And once it was set up, I presented it to my manager who pushed me to present it to the team.

So now, a few months after my team presentation, my little baby project is growing and providing new challenges. Our team is in the process of implementing it and that means gathering content from everywhere it’s been spread out and organizing it on the wiki. Which brings me to the conversion of docs from FrameMaker to HTML.

I tried a couple different methods before deciding on a winner -

FrameMaker to PDF. From PDF, save file as html. Issue: Formatting errors especially concerning images. Would involve too much cleanup.
FrameMaker, save as XML. XML to HTML using an XSL stylesheet. Issue: Worked sorta, but it would take a long time to convert and would need to spend some time creating a style sheet that fit our wiki needs.
Winner: I ended up using a basic WebWorks dynamic html template to generate one html file per FrameMaker chapter. I quickly chose the mapping for the Source to WebWorks style but after a few times choosing the styles, I quickly figured out what I wanted for the output. In some cases, I was able to eliminate some formatting later on by choosing not to output certain Frame items. I still had to do some cleanup but mainly that was around cross-references and updating the file paths to the images.

While there is still some manual cleanup in generating the html files, I am glad to have a pretty easy process to get our current documentation into the wiki. And, I even have a new member of my team helping with the setup of the wiki. Between him and I, we’re going to get our team’s content up, properly formatted, and perhaps even some consistency in the style of the content.

My hope, start 2009 with our knowledge management system in place and ready to be updated in real time. To say I’m excited is an understatement. It’s pretty cool to turn an idea into a reality.

By Popular Demand - The Raiser's Edge 7 for Beginners

Steve Stegelin — Thu, 23 Oct 2008 17:40:00 GMT

We often get great feedback about our documentation from our users. Sometimes, it's a friendly head's up of a typo that made its way out into the world (d'oh!). My favorites, though, are when I get to help fulfill a user’s request or search for information by introducing them to a guide they simply weren’t aware existed. Let’s face it, there’s a lot in The Raiser’s Edge, and as such, there are plenty of guides to browse through (and glance over along the way).

So it was often frustrating to get that one request I couldn’t answer so easily: The request for the “one guide” that introduces the user to everything The Raiser’s Edge has to offer. A simple overview, painted in broad strokes, something for a novice user. Of course this was an obvious need—like I said, there’s a lot in The Raiser’s Edge—and the lack of a good answer was always the most frustrating.

So it’s with much pleasure to finally have an answer to that request with The Raiser’s Edge 7 for Beginners. It’s full of great, useful information, ideal for both the new users struggling with the daunting task of having to grasp everything The Raiser’s Edge offers and the experienced users looking to refresh their memories or explore other areas of the program. It’s also unlike any other user guide we provide for The Raiser’s Edge. Here’s an excerpt:

After you use the program for awhile, you will probably discover other navigation features and methods. Use the ones that work best for you. No way of navigating is necessarily right and no way is necessarily wrong; it’s a you say “potayto,” I say “potahto” kind of thing. Well, actually I usually just say “French fries,” but you get the idea.

Written in this humorous, lighthearted, and simplistic style (not to suggest anyone’s a Dummy), it covers the wide range of features available in The Raiser’s Edge, from records to queries, from reports to mail, and everything in between. You can find it here. (And now I can’t wait for the time a user requests the “one guide” that introduces everything The Raiser’s Edge has to offer!)

Pay it Forward

Lindsey Robbins — Tue, 23 Sep 2008 18:19:00 GMT

Thursday, I’ll be speaking at a college class about technical editing. It’s one of my favorite things to do. I feel an obligation to my field to pay forward the gift my career has given me. I was one of the lucky ones. I stumbled onto technical writing. I managed to get beyond what I thought the field was and discovered, for a closet geek like me ,that it was a perfect place to balance my love of writing with my love of helping others. But I don’t want current and future generations of students to perpetuate misconceptions about technical communication. So when I am asked to talk about my job, I usually accept. After all, it’s not a hard talk when you speak from experience and a genuine love for the field.

Thursday’s talk is at Atlantic Armstrong State University in Savannah, GA. A connection from grad school created this opportunity. Although the unfun part happens today and tomorrow – creating the dreaded PowerPoint. I’ve tried presentations without PowerPoint but discovered for their sanity and mine we needed something to look at while I talked (and talked) for an hour. Have I ever said I can really talk a lot? Well you should know that by the name of my other blog.

So loquaciousness aside (like my scrabble word?), I’m really looking forward to talking about what I do with students. Invariably it always reminds me just how lucky I am and why I love what I do. How do you pay it forward?

Google's Chrome Comic Book Documentation

Lindsey Robbins — Tue, 09 Sep 2008 18:56:00 GMT

The buzz in the online world the past few weeks is about Google's new Internet browser Chrome. In the Technical Communication world, the buzz is around Google's choice to create a help book to explain Chrome. Why the buzz? Well it was done in comic format. I'm not exactly sure why the rest of the Technical Communication world is up in arms. I thought it was a fun play on documentation and not meant to be the complete resource on *how to* use chrome. To understand this momentous project causing all the rage, I naturally turned to our own Blackbaud Technical Writer, Steve Stegelin. Most of you may not know it, but Steve started his career as a cartoonist and technical illustrator. In the meantime he's done some pretty impressive work (on non-Blackbaud hours). Lately, you can find him several places.

Charleston City Paper - Weekly Cartoon, Blotter, Special Covers
SC Statehouse Report - Weekly Cartoon
Illustrated a Book - I'll Be Sober in the Morning: Great Political Comebacks, Putdowns, & Ripostes
And he even generously donates his time to some in-house projects including designing t-shirts, adding illustrative touches to our quarterly company newsletter, and the occasional greeting card.

In our cube this morning (yup, I'm the fortunate one who sits with Steve every day), I asked him a few questions about this Google Chrome thing. I wanted to get to the bottom of the hoopla.

Lindsey :
Why is this Google Chrome comic such a big deal?

Steve:
While it's obviously a good bit of marketing gimmickry to promote Chrome, I think it's a great method to explain just what makes it so different from the other browsers out there. Having Scott McCloud use caricatures of the various developers and designers to pass along the message also really helps give it a personal voice, which is a bit of genius, making it less about the corporate Google than about the team of individuals working to make Chrome succeed. With the open source-ness of Chrome, communicating in this way really helps promote its "by the people for the people" message. And as a fan of the comic medium, it's actually quite validating to see the format promoted as such a "legitimate" form of communication by a corporation such as Google.

Lindsey:
Who's Scott McCloud and why should we know him?

Steve:
When I first started reading comics, Scott was the creator of the fun indie comic "Zot!" He's since gone on to become the closest thing comics has to a "resident scholar" on the sequential art form. You may've seen his theses as graphic novels: "Understanding Comics", "Reinventing Comics", and "Making Comics." Each is an entertaining and informative analysis of the comics medium, from the role of the reader, artist, and historian/forecaster. In particular, I think "Understanding Comics" is an invaluable read, not just for comics but for any type of communication of sequence to an audience… I find myself applying some of the thought discussed in that book to my own procedural writing in our user guides, to great effect.

Lindsey:
Are you ready to do the entire Raiser's Edge documentation set in comic form? ;-)

Steve:
LOL. That might take a while…

Here's a sample of the book:

Society for Technical Communication Summit 2008 Reviews

Lindsey Robbins — Wed, 27 Aug 2008 20:25:00 GMT

Thought I'd give the rest of my reviews for the STC 2008 Summit now instead of putting it off for another day. I've already given a review on the Trends in User Research panel and discussed my session on Writing as an Asynchronous Conversation. If you'd like to hear more about what I learned in these sessions, leave a comment about which one and I'll write up a separate post detailing what I learned.

Getting Real-World Feedback on Your Information: A Case Study by Kori Bevis, IBM
The only negative about this presentation was the overwhelming hotness of this room which caused everyone to be sleepy. Otherwise, it was full of useful information especially as we consider how to involve more users in our documentation usability projects. Kori did a great job explaining how they implemented a client council in evaluating their new information repository web application.

XML the Easy Way: Moving Your Unstructured Content (Word / FrameMaker) to DITA by Todd Aldous
Wanted to see a presentation on Asessing Accessibility of Websites for Users with Disabilities but the session was canceled because of the sporadic internet connectivity. Totally bummed. Showed up in this session a few minutes late and quickly realized that moving unstructured content is easy if you build a bunch of custom plug-ins for FrameMaker. One of only two sessions I regretted going to at the conference.

Guidelines for Effective Captivate Movies by David S. Locke, Wordsmith
Since we're now using Adobe Captivate to create our video tutorials, I thought it would be good to see what other people in the field had to say about what makes a good captivate movie. The foundation of his message was good but thought some of his time estimates might be exaggerated. I definitely think when you first start creating short videos you can spend a lot of time editing, but after you create a few and set a style you spend less time on the details and more on the content. His core issues of context and control, content, communication, focus, and synchronization were spot on. If more people are interested, I'm sure I could co-write a post with Nikki on what we think are important guidelines for video tutorials and screencasts.

So, You Can Write. But Can you Think? by Dawn Maxson, Dell and Deborah Doyle, Sun Microsystems
I really try to be a nice person so let me just say that this session was a complete waste of time. Nothing valuable learned. Would expound but I'd rather not talk badly about a presentation on a blog. I'm sure they had excellent intentions for this presentation. Better luck next time ladies.

Stop Wasting Time: Ten Things You Can Do to Make Yourself More Efficient by Scott Abel, The Content Wrangler
Scott really is one of those people best seen live, in person. Funny, on the edge, and willing to call anyone out on any topic. This was a fun presentation full of some great tips, resources, and websites. My favorite of the 10 tips were #7 - tag and share, #4 mashups, and #3 project management tools. You can see his full presentation on slideshare.net, although as I said above, he really is worth the price of admission.

Mining Web 2.0 Content for Enterprise Gold by Michael Priestley, IBM
Do I wish I were as genius as Michael? Yes, yes I do. Michael did a nice job of talking about the relevance of web 2.0 and DITA and making a case for open standard support for web 2.0. I especially appreciated his discussion on how it's getting easier to get content in but harder to get content out because information becomes silo'd, redundant, and harder to reuse. My favorite thing he said in the whole presentation centered on separating the content from the application of which I am a strong advocate. No matter what application you end up using, your content needs to be solid. In this case, advocating more standards for web 2.0 would enable us to create more flexible, powerful content. Definitely had a lot to think about after his presentation and not the least was how I could someday be as super smart as Michael.

Agile Technical Documentation by Jean-Luc Mazet, Hewlett-Packard
Probably my favorite presentation at the conference. Great balance of humor and bursting full of useful information about the hot topic in software development - agile! He did a great job with overview for those newer to this style of content development and yet also gave advice on things to avoid. For example, as technical writers getting away from "owning" pieces of documentation. The team owns the document and together you write content. When you reuse, content becomes stronger. The most encouraging part of the talk was about how writing in agile really empowers writers and when someone struggles, agile enables coaching until improvement happens. I like that idea much better than the sink or swim method. Jean-Luc wrote a great conference paper summarizing his responses. You can find it on the stc.org website.

Engaging Diverse Audiences using Screencasts, Wikis, and Blogs by Gail Chappell and Cindy Church, Sun Microsystems
Theme of this session? Lots of great examples. Because the project Gail and Cindy worked on for Sun Microsystems was under open source, we were able to visually see examples of every part of their project. I particularly liked the information on the screencasts and blogs because those are both things we are doing and will need to evaluate effectiveness soon. Plus, it's nice to hear other companies discussing their integrated approach to help authoring. It's not all about silos of information and user guides. I like thinking about all the ways content can mix and mash and output in different formats depending upon clients needs. And, I heart examples but I think I already mentioned that above. :-)

Secret Social Session (S3) on new Social Media & Networking by Robert Armstrong
An unofficial, underground STC session was published last minute on twitter and a message board and had a pretty good turnout. It was nice to see my other conference twitterers and have some fun talking about the tools. While what we do is not about the tools, it's still fun to learn and hear about what might be coming next. And, I liked the whole underground movement of the social networking at the conference.

Editing Modular Documentation by Michelle Corbin, IBM and Yoel Strimling, Comverse
Last session ended on a good note. One reason to instantly like this session is we were talking about the content (modular documentation) and not about the tool (DITA). One surprise from the session was the number of hands that shot up at the beginning of the presentation of people whose sole job function was a technical editor. Ouch! Wonder if those people see the future coming or not? I don't know if everyone agrees with me but seems like technical communicators need more skills and flexibility in job function than one that puts you in a small box (especially if mainstream documentation goes the way of agile, then I don't see how you can make your job function only editing). Okay, off the soapbox and back to the presentation. The nice thing about the presentation was that it was well organized, provided some overview but not exhausting, and they had advice not just "we did this, then that". It's nice when people can provide best practices because it shows that they've not only done this type of work but thought through the pluses and minuses. Favorite takeaway - edit for usability not reusability. While reusability is key for technical communicator's work efficiency, that doesn't mean it's important for clients. Usability still needs a central role in evaluating technical communication.

All in all, the conference will definitely be a highlight of my 2008 work year. Thanks to Blackbaud for empowering us through training!!!

How do you like your help?

Lindsey Robbins — Mon, 11 Aug 2008 21:00:00 GMT

In the evolution of software help, user assistance content has taken many shapes and forms. The search for the best way to assist you in your every day work processes is an ever changing quest. Long, jargon filled, and confusing technical documentation is hopefully outdated. And hopefully too, the short picture diagrams with confusing instructions. How did we ever figure out how to put furniture together before technical communicators? However, we know that’s not always the case.

Why is it so difficult to make help easy? Well one difficulty is keeping up with how fast software can change but more so it’s about meeting user’s expectations for help in the program. Here are some questions we might struggle with on a daily/monthly/yearly basis –

User Guides -

When you access help, do you want a user guide?
Do you want to see the user guide on the screen side-by-side with the program or do you want to print it out and go page by page?
Do you take notes when you print the manuals?
Do you want a lot of detail or does that take up too much time and paper?
Are you a visual learner? Do we need more or less screen captures?
If we have more, that’s more pages and bigger file sizes.
Do you have the internet bandwidth to download big user guides?
How do we document everything but not overwhelm you with the number of user guides?
Do you learn by area of the program or depending on the process you’re performing?

Help Files -
Or, are you the type of user who doesn’t have the time for printed manuals and you just want your answer now. You want to search through a help file or knowledgebase and get back to doing your work.

If you are this type, how do you search?
Do you want similar information as the user guide or do you want just problem solving information?
Do you need visuals?
Do you need a glossary or index?
How do you want the help to appear in relation to the program?
How do you access the help? Do you want to hit F1 on the keyboard? Need a question mark icon to click? Or do you miss the days of Microsoft Word when that paper clip would pop up trying to guess when you needed help?

General Documentation Questions -
Then there is the multitude of other questions we might ask ourselves:

Do you want other user’s advice on what works or doesn’t work? Kinda like user reviews on store websites.
Do you want to be able to edit the content yourself?
Add a comment?
Do you want to save the documentation so you don’t have to remember it?
Do we need more web 2.0 types of content and how would we manage it?
And even more so, how can we marry the help files, user guides with other efforts in the company like knowledgebase, training, and support?

These are a few questions jumping off the top of my head. If I quizzed other team members, I’m sure this post would become exponentially longer. We do know from our documentation survey you still prefer having user guides. But we then have to manage how your expectations might change now and in the future. If we don’t start preparing now we won’t be ready then.

This topic really struck a note with me recently because a well respected technical communicator in the field decided to publish content for her users in the form of a wiki and stop creating manuals.

I’m interested in seeing how this goes. I’m aware that her audience needs might be radically different than ours but when you’re focused on day-to-day tasks it can be hard to remember to look out and see how our field is trending. I’m not sure what our users will ask of us in the years to come. It’s exciting and I know whatever you expect of us, we’ll do our best to deliver top quality.

Have any opinions?

Why we need technical communicators?

Lindsey Robbins — Thu, 07 Aug 2008 14:00:00 GMT

Saw this funny post on Holly Harkness's technical communication blog Don't Call Me Tina. It's a funny video that Karen Schriver showed at the STC Conference a year ago in Minneapolis. The video explains for itself why the world needs more technical communicators. I think it's pretty funny but then again maybe I wouldn't if it was real. Thanks to Holly for passing on the video. And if you think it's funny, don't forget to high five your technical communicators for saving you from the likes of Rockwell Automation.

The Rockwell Automation video can be seen on YouTube.

A Great Visual Communication Resource - Worldmapper

Lindsey Robbins — Tue, 15 Jul 2008 16:45:00 GMT

This post is a little off topic from documentation but it's a great resource I came across from my alma mater's listserv.

Introducing... Worldmapper! http://www.worldmapper.org

According to their website, "Worldmapper is a collection of world maps, where territories are re-sized on each map according to the subject of interest… There are now nearly 600 maps."

Did you read what I read? 600 maps for us to click around, play with, and in general become more aware about the world we live in. I especially recommend you spend some time learning a bunch of cool things in the Map Categories section.

366 of the maps are available as PDF posters. This is definitely a great resource if you need a visual to communicate an important point.

Here's an example of a map based on total population…

And another example, based on road traffic deaths…

I guess the traffic in Charleston doesn't seem so bad now.

Documentation is Haunting Me

Lindsey Robbins — Thu, 10 Jul 2008 20:56:00 GMT

Even on vacation I couldn't escape documentation. While most people think technical writers explain software or some similar product (and it's true, I do) so many other forms of technical communication exist. On my vacation I was bombarded with other people's technical writing. It's like one of those things you never notice and then when you're aware of it, it appears everywhere.

Here are a few examples from my recent trip and the time spent in the great outdoors of Northern Michigan.

Planes. Not only did I have neat little instructions with pictures but I also saw a flight attendant reading out of a huge manual. I thought they had to memorize their stuff. And, I know pilots have thick books of instructions as well. Not sure if I'm more or less comfortable with the idea that flying takes so much instruction to complete safely.
I bought a bunch of new gear for camping. I did read the instructions and follow them for my tent, footprint, self-inflating foam pad, head lamp and screen house. I did not read it for my sleeping bag or SIGG water bottle. I should have for the SIGG because I was supposed to wash it before using the first time. Ooops. I'm sure a few chemicals still inside won't harm me, right?
Food. Do you notice how many food packages come with instructions and warnings. I am always reading the labels and not even thinking about who designed and wrote them.
Countless other items I completely ignored as I tried to disconnect for a few days.

Interesting observation about the camping gear. Years past the product pictures and instructions that they crazily throw in last minute were more frustrating than helpful. This time, I actually could figure out what to do based on the instructions. Either I'm getting better at this documentation interpretation thing or my field is improving. You decide. :-)

Why does web 2.0 matter?

Lindsey Robbins — Fri, 13 Jun 2008 11:52:00 GMT

I know I write many (and long winded) posts about web 2.0 and my little brain gets excited about all the new technologies that emerge every day. But how can I not? I am sitting mere feet from software engineers who are part of this innovative movement to change the way we use technology. I would talk about them more but we have other people around here (for example, people named Shaun) that can speak far better than me about the Infinity platform and sites like the Blackbaud Labs. So I like to learn about and talk about things in the web 2.0 world that really speak to me as a technical communicator, a geek, and an everyday girl.

If it's hard for you to picture the connection between our software, documentation, web 2.0 websites like twitter, facebook, del.icio.us, google reader, etc and concepts like social bookmarking, rss feeds, blogging (and microblogging), mashups, wikis, podcasts, and more, think of it this way. The more innovation in how people communicate with each other the more we need to innovate in software and software documentation. How much has software changed in the past twenty years. It's legend around here how in the 90's Blackbaud decided to create The Raiser's Edge on an operating system named Windows. And now, with our new Infinity platform, we are part of this exciting movement in software that's more flexible, powerful, and adaptable. And I'm not just influenced by our products, I'm influenced by the social software on the internet. You now expect to interact with software and people differently because of the applications that have emerged over the past couple years.

On our team, for example, our help file is improved on the Infinity platform. Because our technology capabilities expanded and the software our team uses to create the documentation improved, we are able to provide a more robust search engine that makes it easier for you to search for help content. Would we have been able to do that without websites like Google that changed how we expected to search for information? I'm guessing not. New emerging trends have things like folksonomies where users create the tags that identifies information they find. Someday, I hope the industry that creates software for technical communicators (for example, Adobe), can help us create documentation that enables us to include social bookmarking. Wouldn't that be cool, eh? We have lots of cool ideas on our team that we jot down and then work to make happen. Change takes time and patience (which I have little of sometimes). But, as we work on improving you're still changing. And we listen. We keep our ears and eyes open to what your needs and expectations are so when we can, we increase our capabilities to bring you the best user assistance content.

In other ways, I'm also just learning about how people need to use information in their real lives and not just in virtual communities. You expect different things from us and your software than you did ten years ago. After all, that's probably why this regular Blackbaud employee sitting in a regular, gray cube is talking to you through this blog. Chad Norman, is one of our web 2.0 gurus (if not THE guru) who is leading us on this journey to interact better with our clients. He's very encouraging but even I wonder, what the heck am I (one of approximately 1,700 employees) doing writing a blog on the company website? Even if it is weird for me, I still write because I don't want to pass by this opportunity to interact with our clients, colleagues, company leaders, and the technical communication world. It's just too inspiring and too cool to be a part of innovation.

From my perspective, I'm very excited about all of these changes. They force me to grow and they help me stay involved in the process. Just because I do sit in a gray cube, in a sea of gray cubes, doesn't mean I don't want to know how our clients work, how they make a difference, and how in whatever way I can, help make their day easier.

Be a Part of the Conversation

Lindsey Robbins — Mon, 09 Jun 2008 21:48:00 GMT

How often do you think about the conversations you have with your constituents or users? Are you thinking about the synchronous real time conversations - the phone calls, the meetings, the special events? If you are, you're overlooking one of the most important conversations you're having with your members, users, or constituents. The conversations we have that aren't in real time can make or break your success. Some examples of asynchronous conversations are reports, journal articles, policies and procedures, legal notices, emails, websites, twitter, SMS, promotional materials, and more. No matter the medium, every user is seeking an answer.

This concept was perhaps the most interesting from a thought process perspective from the conference I attended. The session I attended was from Ginny Redish on Writing as an Asynchronous Conversation. It made me think about how I write and how every piece of documentation we write is an ongoing conversation with users.

So, whenever you write something, ask yourself, what question am I answering? You can see if you're answering questions by looking for the verb. Conversations usually start and progress with one. For example, check out Amazon.com's login page. What question are they asking you?

In the software world, we've been answering questions for a long time. A dialog box is a form of question. Do you want to delete this very important file forever and be doomed two days from now? Click Yes or No! We, of course, click No and curse ourselves out later. However, the key element is the program asked me a question. The conversation was started by the software and I gave a dumb answer, but an answer just the same.

Over the years, in software documentation we've added more conversations via context sensitive help (F1), help files, user guides, tutorials, and more. No matter how we do it, we have to evaluate whether we are answering your questions. If we aren't, what can we do better? See, another question!

I suggest you ask yourself the same thing. How are you doing in your conversations?

For example, try answering these questions -
"How is my money being used?"
"How can I help your mission by volunteering?"
"When is your next special event?"
"What is the latest news from your organization?"
"The economy isn't great. I don't have a lot of money, but I want to help. What can I do?"

How did you do answering the questions? And, more importantly, where are you answering them? We can't always rely on real time conversations to answer questions, we have to be effective with every means of communication or software available.

Sometimes, your users or constituents won't know the correct question to ask. In those situations, try to think out the questions for them and answer them in advance. Provide them with the conversation starter and they're more likely to be engaged.

And remember, people don't have an infinite amount of time. They really will only participate in the conversation long enough to get their answer. Therefore, all your communication whether it's real time or not needs to be concise, clear, and efficient. Don't provide lots of and lots of text that users will balk at when they see (for example, this crazy long post is not a good conversation starter ). Keep your answers to the point, ask yourself if you're answering a question, and validate by having others review your work.

After all, it's not really computer to human interaction. There is a person on the other end of the computer and they need human to human interaction. All these great tools like Twitter, Facebook, Google, Raiser's Edge, Blackbaud NetCommunity, Education Edge, and more are tools. They are the medium that connects you to your people. Are you using the tool to create conversations?

Here's a short reminder…
1. Keep conversations short and on topic.
2. When you write something, identify the question being answered.

And remember, over these short asynchronous conversations you're having with constituents, users, and members, you are developing relationships. It's not always about making the pitch where you win or lose people, it's how you handle the short, quick conversations on a daily basis.