From the Doc Side : humor

User-Generated Help: Future of Documentation?

Lindsey Robbins — Wed, 26 Nov 2008 18:07:00 GMT

Of late, I’ve been intrigued by something YouTube is doing. They are requesting user-submitted documentation in the form of videos. Well the video part makes sense, right? However, it’s interesting they are reaching out to the audience to supplement their official documentation. Is it fair to put the burden on the users? Fun for users to participate in developing help?

They are now doing a second round of submissions. You can read about it in their blog. And, you can review the round one selections.

One interesting thing, they didn’t ask for just any help submission, they provided a list of topics to choose from. If your video is selected, it is then posted side-by-side with their content. And, they claim their help gets 1 million + users a day. Not sure if I believe that or not but it’s still interesting (I've never clicked on the their help but maybe I'm an anomaly).

This is definitely a topic I’ll keep my eye on as help and documentation might be figuring out how to join the web 2.0 world. But then the question still remains, when do you ask for user-generated help? I mean, it might be a pure guess on my part but I don't see a million people rushing to create help content. Most people would rather visit the dentist then spend time explaining things to others. Unless you're like me. And if you are, welcome to my ~~crazy~~ cool world.

Vintage Documentation

Lindsey Robbins — Fri, 31 Oct 2008 14:52:00 GMT

Wired magazine published a great photo essay on classic instruction manuals. It’s funny and pretty cool to see how far we’ve come as a field. Although my team is in agreement, that poor guy from Apple - what was he thinking selling his share of Apple stock for $800?!

Check out the photo essay here:
http://www.wired.com/culture/design/multimedia/2008/10/ff_manuals

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:

Rise Above the Tools

Lindsey Robbins — Tue, 19 Aug 2008 19:56:00 GMT

It’s not about the tools. This is what I always tell myself and this week is a prime example of why it’s more important to rise above the tools and focus on what you’re getting out of it than to focus on mastering the tool. Why you ask?

Well because sometimes, even with your best intentions, tools can do weird things and laugh at you. In those times, you need to be smarter than the tool, or just laugh at yourself and try again tomorrow.

Let me set the scene –
I’m working on generating help files for EE/SIS. We were having an issue with some hypertext markers we use to link one part of the help file to another. I realized I needed to change part of the marker.

Specifically, I wanted to change

gotolink //Ntpd/docs/EA_FE/EE_FE_SIS_777/manuals/…
to
gotolink //Ntpd/docs/EA_FE/EE_FE_SIS_777/Manuals/…

yup, all I wanted to do was change the lowercase m to an uppercase M.

Then, I clicked the Edit Marker button.

What did Adobe FrameMaker do?

It changed Manuals to smanuals. Yup, you read that right, it completely changed a word on me.

smanuals

What in the world? I think I made the god of tools (whom we dubbed Mechanisis) really mad because in all fairness Adobe FrameMaker has been good to me the past few years. This isn’t normal. Software doesn’t usually change words on you. What do you do in these situations (besides make your cube mate laugh at you so hard he was crying)?

You rise above the tool, you fall back on your common sense and experience to remember that you can endure even the strangest of tool interferences. Software is always going to be evolving and changing. Even experts on explaining software have hiccups in the road. It’s what you do to move beyond the problem that makes you successful.

And you know what; today I generated the help file after figuring out a work around. Not only did I overcome the smanuals, but I managed to fix the error we were having with our broken hypertext links.

Call 'em smanuals or manuals, I don’t care as long as I can reach a happy ending.

Klingon Technical Writers

Justin Baden — Fri, 15 Aug 2008 18:25:00 GMT

Ok, so if I had to pick one, I’m definitely a Star Wars guy... but Star Trek is still in the mix. Regardless of where you stand, whether it be with the Rebel Alliance or Star Fleet, one thing is true... Klingons are no joke. And as tech writers, they’d be no nonsense in the way they handle their business.

As proof, I present the following list, which I came across back in 1999 and saved because it's awesome. I know it’s been circulated around the web in many forms, altered for various job titles, but here’s the classic tech writer version. BTW -- if you know who wrote this or where it originated, drop a note in the comments and I'll update the post to give credit.

So without further discussion, here are the top 15 things likely to be overheard if you worked with Klingon tech writers:

15. Certification?! Having your hot blood dripping from my glistening blade is all the certification I need!

14. I will return to the homeworld and my documentation will arise triumphant in the STC Documentation Gauntlet, leaving all others drowning in their own dangling modifiers. It will be glorious!!

13. Not returning my review copies by the agreed deadline is a declaration of war! Indeed, it is a good day to die.

12. These specifications are for the weak and timid!!

11. This version of Word is a piece of GAGH! I need the latest version of FrameMaker if I am to do battle with this manual.

10. You cannot really appreciate Dilbert unless you've read it in the original Klingon.

9. Indentation?! I will show you how to indent when I indent your skull!

8. What is this talk of "drafts"? Klingons do not make document "drafts." Our documents escape, leaving a bloody trail of SMEs in their wake!

7. Use of passive voice is for the weak. They will not survive.

6. Proofreading? Klingons do not proofread. Our documents are purified with pain-sticks which cleanses them of impurities and weakness.

5. I have challenged the entire Marketing team to a bat'leth contest! They will not concern us again.

4. A TRUE Klingon warrior riddles his document with bullets, leaving it to beg for mercy.

3. By changing the layout of my manual, you have challenged the honor of my family. Prepare to die!

2. You question the worthiness of my grammar? I should kill you where you stand!

1. Our competitors will know fear and cower before our suite of manuals and online help! Ship it! Ship it and let them flee like the dogs they are!

Update! The orignal author of the Klingon tech writer list has come forward... it's JD Hickey over at Docmentia Inc. Thanks for the laughs!

Meet the Team - John

Lindsey Robbins — Thu, 07 Aug 2008 18:54:00 GMT

Name? John Lyons

How long have you been at Blackbaud? 1 year

What technology from the past do you wish would make a comeback? Well, I’m still waiting for one of those hoverboards from the Back to the Future movies. Does that count? It’s not really a comeback since they never existed, but way back when those movies came out, I remember reading that everyone would have one of those things by now.

Favorite part of technical communication? The fact that there is always something new to learn. Whether it’s new features in our programs, ways to tailor documentation to our users’ needs, or the technology behind the programs, there is always plenty to learn. The work environment at Blackbaud is great, and it offers plenty of learning opportunities.

Products you work on? Blackbaud Enterprise CRM and Blackbaud NetCommunity

Other projects you work on? I’ve been working on a consistency project to create a style guide for products on the Infinity platform, and I handle updates to the sample database for The Raiser’s Edge. I’ve also been learning Visual Basic and trying to familiarize myself with VBA and API in The Raiser’s Edge.

How did you get into technical writing? Just lucked out, I guess. After working for newspapers for about 10 years, I decided for the second time that I needed to get out and move to something more technical. (The first attempt was back in 2000 when I started studying computer networking and got the CCNA certification. Unfortunately, I managed to get my certification just as the dotcom bubble was bursting.) Luckily, this time around my sister worked at Blackbaud and passed along my resume. … The paper where I worked just started a “voluntary separation program” to buy out employees, so it seems like switching fields was a pretty good idea.

What's changed about Blackbaud since you've been here? Lots of new faces. I’ve only been here for a year, but even in that short time, it seems like we’ve hired a ton of new people. The ones who are fresh out of college make me feel REALLY old.

What hasn't changed? The great work environment. All jobs have their ups and downs, but the positive work environment at Blackbaud and the great coworkers make a huge difference.

What's one unique thing about you? Nothing really … Although I do have an inordinate number of pink shirts that I actually wear on occasion. My wife buys them and claims to really like pink on me, but I suspect she just gets a kick out of seeing me look silly. However, there might be more to it than that, because even before she started buying all those pink shirts, I had one pink button-up that I’d wear occasionally; maybe a few times a year. When I wore it, I consistently got compliments from female coworkers. A coworker picked up on this and started wearing pink too, and he got the same response. So either women really like pink dress shirts, or they just like when guys look silly. Or maybe both.

Anything else? Well, as much as I like my job, the best thing about working at Blackbaud has nothing to do with work. My favorite perk is a pickup game of basketball with some guys who work here. Twice a week, we play ball before work from 6 to 7 a.m. I’ve been told by more than one person that I’m crazy to get up that early, but it’s really one of the best parts of my week.

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.

Jumpcut - Online Video Editing Tool

Lindsey Robbins — Mon, 28 Jul 2008 13:50:00 GMT

Now that our team’s Docs Day 2008 (team training day) is over, I can start sharing all the fun surprises I had for them in my presentation. I presented on my trip to the Society for Technical Communication Summit in June. I’ll be posting reviews on each presentation I went to as I promised in an earlier post. In the meantime, I wanted to share a fun new tool I used for the lunch time entertainment.

I found this site – Jumpcut http://www.jumpcut.com

Jumpcut is a website that makes adding, editing, and sharing video online easy. In 2006, the company was acquired by Yahoo but I don't think it's taken away from this fun, feature rich site. For me, the easy to use editing part was the reason I chose this site. I had embarrassing footage of me doing the Rocky impersonation in Philadelphia and wanted to add the Gonna Fly Now music to create a silly video of me for my team to laugh at. Then when I started playing on the site it was easy to add photos, more music, and transitions. The only issue I came across was trying to figure out how to transition the music. Also cool, people can remix your video or you can give them permission to edit. The features are all easy to use and the learning curve isn’t that steep. In the end, you have a **free** video you can share with others.

At risk of further embarrassment, I’ll post the video here. Warning – it is 8 minutes long! (I got a little out of control). Also, in the beginning I was making fun of the opening session by posting a picture of each person who presented something before the keynote speaker. It just went on and on! Once you get past those though, it’s all pictures of how much fun I had in Philly.

Enjoy a good laugh on me!

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. :-)

The Funny Side of Help

Lindsey Robbins — Fri, 20 Jun 2008 20:26:00 GMT

The more I explore help on the internet the more I see humor being used in documentation. Most of the time, I appreciate the unexpected approach to help. But, am I the exception? I’ve often heard how difficult it can be to use humor effectively. Humor for the most part is not a universal language across cultures. We’ve been taught in technical communication to write as one voice. I still think it's a valid point because inconsistency in language can drive me bonkers. However, is the movement towards folksonomies and relaxed language in explanations pushing us towards the point where we can be completely casual with our users?

I’m not entirely convinced. It seems to me it depends on the software you are explaining. A site like Twitter or Flickr can be edgy because of the type of content it manages. Software in the business world doesn’t necessarily seem like ripe ground for experimentation. I do think though that exploring what language you use is a valid discussion point. Do we need to be formal? Does being too formal make reading for understanding more difficult? I know when I read for understanding I like to feel like the writer is talking to me instead of in a monotone generic voice.

What language do you use in your communications? Have you used humor? Or, do you have an opinion on the language we use in our help files and user guides?

If you have some examples of some funny help documentation, be sure to share those too.