One of the roadblocks Technical Writers experience quite often, especially in software documentation, is overcoming obstacles in the usability of our doc. In a fast-paced environment like software development, staying ahead of the curve is important, of course. There is always a new program or product to help us write our doc. But will our company invest in it? Is it worth the cost? It’s expensive to train teams on the technology, right? And integrating those new features into existing documentation is not seamless. Competing programs don’t typically work seamlessly with each other. I just read a post about the most valuable tools to tech writers, and while many agreed that Madcap Flare is the tool du jour, that came as no surprise, since a handful of the writers referenced in the article work at MadCap. Other tools noted included Camtasia, Adobe products and even my personal nemesis, Acrolinx  (In a later post, I’ll explain why I am not an Acrolinx fan, but let’s save that for another day.)

While the tools we have at our fingertips certainly have a great impact on the work we are able to produce, we as writers can lean on those tools too greatly if we overlook the simplest of design elements and forsake the foundation of what our documentation must be in the first place: usable.

We know that Technical Documentation has a utilitarian function. It has a use purpose: it meets a need of the user because the user requires documentation to, say, install a product. So we have already jumped the first hurdle of the UX measure by designing something that fills a customer need. Check that off the list.

The second hurdle is Usability. We must jump this hurdle by creating something that is easy. In a UX model, we are tasked with creating something that can be navigated with ease. This is where our tools come in handy (or not). If our customers cannot use our documentation easily, we have not cleared this hurdle. Think of the handheld electronics that come packaged with the foldout instructions in print so small that one needs a magnifying glass to decipher even the battery installation. Do we really want to continue that trend? Of course not. Creating easily-used documentation is key.

The next area is Desirablility. Normally, in the past no one thought of technical writing, least of all something like software documentation, as having a desirability factor. Well…I’ve spent a good bit of time creating some YouTube videos that are not necessarily going to win any MTV awards, but they are not exactly difficult to watch. If my customers desire the video over the lengthy text, so be it. This is why a tool like Camtasia or Captivate9 is my favorite tool today.

If my customers feel no pain in clicking through the doc I’ve created because the experience is smoother than tabbing a PDF, it’s a win. In today’s field filled with rich media, documentation is often more off the page than on. Creating pleasing ways of reaching customers with information is an essential piece of the puzzle. So, if I can set up something for a customer whose reaction is more or less, “I like the way this looks,” or “I’ve had a satisfying experience,” then my goal is achieved. It’s why I often marvel when any company is reluctant to jump on board when a technical writer shows management the latest tool toward potential great documentation. (If any of you in management anywhere are listening – equip your writers with the stuff they need to get truly creative. You are unlikely to regret the monetary investment in truly slick presentations, but you are very likely to regret being late to the game. I’m just sayin’.)

Last on the list is to create an overall satisfying Brand Experience. When the other hurdles have been cleared – and generally only when the other hurdles have been cleared – the Brand Experience can be a positive one, because the Utility (need), Usability (ease of access), Desirability (want or perceived want) have been met, and they lead to loyalty. According to J. Josko Braus, of the University of Rochester, brand experience is primarily a sensation or a feeling, but it is part of a brand’s “identity, packaging, communications and environments.”

Braus points out that when customers first engage with a product, they are engaged with its “utilitarian product attributes,” so in this case, my customers are engaged with product documentation (after all, as a technical writer, I’m really selling my doc, but on behalf of the product at large. My customers will associate that documentation with my company’s name, logo, and more, but only on a broader scale. I can hope that customers will be delighted with the overall experience of the end-product, but only after they are satisfied with the Brand Experience they’ve had with my doc.

I could get all academic here, and take you down the rabbit-hole into the debate surrounding Brand Experience, but my focus is on User Experience and how it centers in documentation. If Usability is all about being able to use something, then the User experience differs here because I want my users to be able to have a good feeling about using my documentation – to experience it in a way that enhances their overall engagement with the documentation.

Think of it this way: a usable stapler is one that performs the task. It staples papers together.

And yet when you have mastered the hurdle of mere utility, you can also move ahead with usability, desirability, and brand experience. Because who wouldn’t prefer a really good-looking stapler?

 

In the days of Waterfall Software Development, nobody wanted to pay much attention to Doc Development. I mean, let’s be honest. It was the second-to-last step in the whole process, and pretty much the least glamorous. Although documentation had the potential to occur at any point in the product life cycle, as we have proven with Agile methodology, everyone saved it until near the end, believing it had to be placed until after all of the development, coding and testing was complete, but until before packaging was ready.

We now know that Doc is part of the system, an integral one at that, and yet sometimes it is still the redhead in the room, not getting its due unless it steps up with its fiery temper, begging for the attention it deserves. We know that in some very successful organizations, Documentation gets a well-earned 20-40% of total development effort, while in other organizations, it falls by the wayside, and that lack of effort shows. A perfect example is any company (and there are many) who believe that good technical documentation can be cut in the budget, because support can handle the issues, only to discover that one call to support costs far more than creating good documentation in the first place. Content Strategy 101 offers some insight on the fallacy of low-cost documentation.

So with today’s evolving documentation practices, we have to work hard to improve that documentation mousetrap. We don’t build manuals any more. We don’t ship CDs with pages and pages of tiny-print leaflets of unreadable instructions, so what are some ways to make our ever-evolving documentation relevant?

I suggest that there are a top 5.

Of course there are more like a top 100, but if I put them all here, I will have blogged myself out of a job and I’ll be the irrelevant one, so stay tuned for future blog posts with other super-engaging titles like “Top 5 ways to Test Your Doc!” and “Coordinating Internal Systems!” you get the gist.

For now…

#1

Give User Examples

In Online Documentation, unlike print matter, there is room for Use-Case. Scenario-Based Documentation is popular now, so learn to make it your friend. The SBC is an online user’s friend. Embrace the SBC.

Examples are a superior way for end users to see and experience concepts that are difficult and new. An end user learning new software can experience the software much more easily with a walk-through than with just a third-person explanation.

Switch to second person and allow for a full flow. For example, “When you click on the water icon, you see the mermaid swim across the screen.”

#2

Use Diagrams and Images if Possible

This seems like everyone already knows it, and yet they don’t. OR, if they know it they are not doing it. When the internet was young, everyone was slapping pictures on everything. All of a sudden, we are back to wordiness. I’m a fan of “a picture is worth a thousand words.” Explain a process with a picture, will ya? Not everything needs a photo, but a process sure needs a diagram. If you can minimize the complexity of your documentation by offering a table, do it. Or if you can make it a bulleted list, get on that.

#3

Assume Nothing

You may not know your audience, but presume that they know even less than you do. If you think that the average user is pretty well-versed in computer skills, and you want clutter-free doc, at least take a moment to offer a hyperlink to a basic skills set in an appendix for those who know pretty much zero. Change your mindset to that of a brand-new user who has never seen this stuff. Fully document the process from beginning to end, and then go back and follow your process.

#4

Anticipate Difficulty

Try to break your stuff. You have QA testers who have tried to find issues with the software, so you should try to find issues with your documentation. If the software you are writing for has defects (end users call them bugs) you’ll need to document workarounds for those, providing useful ways to save your users calls to the help desk or support, and proving yourself to be a very useful doc writer. This is a tender spot to be in with developers and testers, but your relationship here counts.

If you are working in an Agile environment, (most of us are these days) you can usually test as you go. You’ll get smaller chunks of doc to try out, in smaller increments, which is nice. Find the zones where your doc is unclear, or could be clearer, and prop it up.

#5

Explore New Technologies

Hey, Documentation is expensive even when it is done correctly, implemented flawlessly and delivered on time and on budget. Doc departments cost money, and we are not the primary product. Is it any wonder doc departments are often trying to justify our very existence?

New technologies will perpetually be the key to creating more effective documentation that is less expensive to develop. New tools are opportunities to reduce time and the cost of the whole process. Look into text-to-speech. Look into better visual editors. Check out the latest in fill-in boxes, component editors, macro checkers – the whole shebang. You will cast aside 90%, but you will find some of them are magical. Remember the little paperclip that sounded like it was tapping on your screen?  Annoying, yes, but nifty nonetheless. Remember the first time you opened Power Point?

Holy cow! Remember the first time you checked out GeoCities?   Now think about the first time you edited in Adobe. Or edited your content into 140 characters.

Check out all of the ways to document.

Myriad. Seriously. Mousetraps upon mousetraps.

And the mousetraps are getting better. The mice are smarter. But the mousetrap builders are pretty smart, too, and we are acquiring better ways to go about it. So don’t move the cheese, just build a better trap. Follow the documentation, and you will have all you need to get the job done right.

 

 

 

Almost all of us have those experiences. The ones where we “love the ambience” – of a restaurant, someone’s home, or even a park, a beach or a vacation spot. The way a place makes us feel is significant to us. But the word ambience has a more important origin. It hails from the Latin verb ambire, meaning “to go around.” It meant more of something that encircled something else. It was a verb, after all. In its current usage, it is a noun when it is used as ambience. It is an adjective when used as ambient, as I will here – ambient light, or ambient sound. There is a whole career  in which someone chooses the music to be played at a restaurant – the ambient music for your dining experience. Just the right song list for the evening.

But I’m thinking not just of music or lighting. I’m going more along the lines of the whole realm of other things that impact our daily lives. Because, you see, we have infiltrated our living with ambient computing – the ability to access and harness computing power is truly all around us, all the time. Not all that long ago, say right around 200, even, if you needed a bit of information but couldn’t recall it, you jotted it down – on your Palm Pilot, no less, and looked it up on your handy home computer when you could get to Google or a then-new Wikipedia article. Now, though, information is – quite literally – in the air. Peter Morville writes in his recent book, “Ambient Findability, ” about how to filter through the rampant deluge of instant information to get to what we actually need. Morville actually takes into consideration the evolutionary path on this journey – and that’s no small task. Is findability as essential as we think? Well, I’d argue that if information is our new ambience, then yes. Finding our way through it is a key element.

In computing (and here is where the intersection of my writing and my technology comes in – why I am interested in this whole word thing), there is the great concept of “calm technology.” The aim of calm technology is to reduce the information overload, or the ambient noise experienced by the brain so that the user can decide where to focus his or her attention so as to get at the most important or useful information. In my job, this means keeping pages user-centered, clean, and focused and free of things that you see elsewhere on the internet, like pop-ups and flashy distractions. While I do not want my material to be boring, since that is a distraction in itself, I likewise do not want there to be dancing monkeys in the corner of the screen. Dancing monkeys do not represent calm technology. Crisp, easy-to-access writing does.

For technical writing, the sense of calm comes from ease of use, from that ambient findability I mentioned before. Think of a meeting with your supervisor where only he or she knows the agenda to be discussed – you, as the invited attendee, feel very uncomfortable (not calm). But once the agenda is published and you know that the topics are clear and nonthreatening, you feel at ease (calm). The same works with technology. In technical prose, if the topics are clear and easy to access, the environment is calm. It’s a good ambience.

A video conference or a live teaching tool in user training can likewise be calm if it’s done properly. In our organization, we use monthly customer demos not just to show the work we’ve done, but to preview what we are working on, to sometimes lift the curtain on what’s to come – to create that calm ambience. It’s a good move. With all customer interactions, it’s just like that meeting with the boss – if the information is clear and accessible, the ambience is great. The metaphor works whether it’s tech or not, but let me bring it back around to specifically technology.

Calm technology, if we are lucky, pervades not just technical writing, but our work, lives, and homes. For instance, the calm technology that I have here on my desk includes two monitors. I use my laptop monitor for smaller things that perhaps don’t need my full attention – my email registers there, and my skype  screen, for example. I do my editing (like this blog) and my reviewing of documentation panels for my job, so that I can compare draft and final versions side-by-side. At home, I use a wink app  to make life a
whole lot simpler, from turning on and dimming lights to locking and unlocking doors. I integrate an Amazon Echo and soon I’ll order an Echo dot to simplify that even more. Learning, interacting with occupant behavior – all calming technologies. They make my space feel better, run more smoothly, interact with my world a little more easily. That’s the idea behind ambient computing, if we really reclaim the word.

Now, if only I could get these things to go to my early morning yoga class for me?

 

There’s a running joke among my development teams:

Mockingly, we act out the following scene:

Customer, or other interested party asks:

“You have a question about the software?”

Developer, tech writer or other knowledgeable party replies:

“Yeah. The answer’s in the doc.”

All other interested people within earshot chime, in unison:

“Of course it is, but who reads the doc?”

After this exchange, I always smile, shrug my shoulders, and go back to writing more of the doc. I got my job in large part because I have a fairly impressive array of English degrees, assuring those in my company that I could write some coherent documentation. But does anyone read the doc?

Writing a technical document is difficult. Reading documentation that is poorly written is even more difficult, and likely more challenging than writing it. It takes diligent effort to create clear, accurate prose that engages readers, and if it is software documentation can it ever be engaging? Does anyone want to read this stuff? I have trouble imagining the scenario where someone is eager to sit down and sink into a piece of thrilling prose about how to install a new update! But I suppose anything is possible…

While there are a handful of guides out there to improve your prose, I thought I would start my January off with just seven little “rules of engagement” that I try to keep close at hand when I write Software Documentation.

Now, bear in mind, this does not apply to all writing. I just mentioned to a colleague the other day that I may not win any awards this year for great American fiction (though I do have an upcoming creative nonfiction essay due out in April, but I’ll clue you all in to that later. This advice is strictly about Technical Publications, and more specifically in the narrow field of software doc. (Forgive me, I had some fun with the links – see, finding the fun in technical documentation?)

1. Dry is for deserts – You read that right. While you don’t need to pepper your doc with humor, sarcasm or literary devices, it also needn’t be free of lubricant. Write in first-person, use active verbs, and try to paint a picture for the user. In other words, do not write uninteresting prose.
2. Imagine what your reader will do before you write – This will help you write clearly. If you can envision the process, you can create the words. Walk your own self through the steps, and use that as a guide.
3. Prepare an outline, just like in college – I wrote outlines for every other kind of writing, so w
   hy stop now?
4. Avoid ambiguity always – (I’m dying to mention something about alliteration, but I won’t) This is a big one. Just be clear, and everything will be, erm, clear. I used to teach my creative nonfiction students that it was supremely important to not just choose the word but to choose THE word. That still rings true.
5. The road to clarity is through a combination of words and illustrations – If a picture is worth a thousand words, imagine what a picture PLUS some words will do for you! Add a graphic or a diagram, and the technical prose you create is just pure magic. If you are explaining a tough concept, map it out.
6. Tough concepts require logic, so use it – Get a good book of logical explanations  (An Illustrated Book of Bad Arguments is actually a really good one)nand apply them. Do not ever stoop to saying, “That is as simple as it gets,” because that is just not true. Make a concept simple, and then make it even simpler. That’s the job, after all.
7. Look at revision like it’s your best friend – If you cannot enjoy the art of revising, then this job is just no fun. The whole idea is to try to shape and reshape and finesse ideas in fun and innovative ways. The work is never done, or we will work ourselves out of a job. One day, all of the doc will be written, so if there is no revising, there’s no more work. Until, of course, there is more software! So thank goodness there is always more software!

Continue reading →

The first time I heard this expression, it was used at a “Women in Tech” conference, by the inimitable, unflappable Debra Lam. Since I’ve long been a women’s studies scholar, first nailing down my degree in Creative Writing at Slippery Rock University, where I dug in deep in the ideas of women and film, women and parenting, women and everything…I was intrigued by the application of a Bechdel Test for IT.

For those unfamiliar with the Bechdel Test, it is this:

First applied to film by graphic novelist Alison Bechdel, creator of the comic “Dykes to Watch Out For” and the graphic novel turned Broadway musical, Fun Home, the Bechdel test has three simple rules – a film must have (1) at least two female characters who (2) speak to each other about (3) something other than guys. You’d be surprised how many films fail this test. The Harry Potter films fail it. The original Star Wars Trilogy fails it. The Social Network fails it. Even Minions fails it. Sigh, Pixar.

So what does some feminism test for films have to do with the high-tech sector and tech writing and jobs, you might ask? Well, for starters, I spend a decent amount of time reminding folks that although I am a writer, and I will always be a writer first and foremost, my job is indeed in the tech sector, therefore, I am a woman in IT. Go figure. I spend a fair amount of time mingling, or trying to mingle, with other women in tech. I spend some energy encouraging young women to think about tech in new and different ways. I enjoyed reading Gone With the Wind  as a young teen girl, and my first BA is actually in theatre, and in my spare time I write Creative Nonfiction. I subscribe to The New Yorker – I’m into literature. My second MA is in English Literature with a concentration on the female voice. But I digress, because my job – the job that pays me well, the job that interests me every day and keeps me excited – is the job I trained for, and it is high tech. And this Bechdel test for IT asks us to hang out at any gathering for tech women and listen to a panel of speakers to see if those speakers can possibly talk to women in tech without asking,

“Why are there so few women in IT?” “Where are the women in IT?”

Instead, look at the women in the room and say, “Let us empower you to do the best job you can. Let us give you the tools to create stronger paths, better examples for those who are watching you from home, from school, and from outside the workplace so that they can see what a cool job you have.”

At this particular conference, I was struck by how many women indicated that their role within the tech company for which they worked was in HR and how few were programmers, but then I wondered if their respective companies had sent them on a bit of a hiring mission – fair enough. Gather resumes, business cards, expand our network. Fair enough. We all want to grow. So let’s grow. Stop asking, “Where are the women in IT?” We are here, we are writing, we are hiring, we are watching one another work, we are just not making it look terribly glamorous yet is all. We just need to set the parameters for the Bechdel test.

Another woman at the conference was a fantastic speaker and leader named Tacy Byham. Tacy is the CEO of DDI, a local (to me) Pittsburgh-based company. It is actually a global, world leader, but I’m lucky enough to have her in my hometown. One of the things Tacy mentioned at this gathering was the propensity to “lead like a girl.” It was brilliant, because by the time we are women we’ve constructed all these false notions that our leadership is somehow different than it is from men, and yet it isn’t. When we are girls, we are every bit as capable, we think we are every bit as strong, smart, fast, clever, you name it – but then we alter our perception and somehow we think we are not. We think we are less than, and we let the guys step in.

When I left for my first semester of college in 1988, I took with me an Apple IIGS, one of the first real personal computers, and a binder full of floppy disks for Print Shop Pro. I had no idea I would be an English professor and eventually land where I work now. But being open to concepts like the Bechdel test, writing as a form of technology, not pigeon-holing myself as “only literary,” and diving in to new concepts and methods – all of these things mean that if I can loan that concept to just one more woman who is entering the workforce in IT and not ask the question “where are all the women in IT?” it is a win for us together. Because the woman I am talking to, writing with, who is collaborating with me then and there – SHE is a woman in IT. She is a woman in leadership. As Tacy put is, she is leading like a girl.

So, as 2016 approaches us, let’s all give the Bechdel test for IT a real shot, shall we? No more “where are the women…?”

Because – here we are.