A User Experience View


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.

Ugly stapler

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?


Building a Better Mousetrap, or Better Mousetrap Documentation Anyway



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…


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.”


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.


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.


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.


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.

Behe's mousetrap




Busy is Not Productive if It’s Just Busy



All too often, and more so on the weekends, we find ourselves saying, “I’m too busy to do that,” or “I’m too busy all week at work,” and other phrases quite similar to that. The Next Web writer Sean Kim recently wrote a column titled “Why telling ourselves we’re too busy is bullshit,” highlighting the idea that busy is different from productive.

We are asked to be productive all the time. In our jobs, the management structure or clientele certainly demand productivity. At home, if we are not productive, we have creeping lists of things that simply never get done. Busy-ness can get in the way of that productivity if what we are really doing is postponing the important things, or mis-prioritizing altogether. Kim points out a list of attributes that separate busy people from productive ones, including what in my industry is called “WIP,” or work-in-progress.

People who have too much work-in-progress always seem busy, and in fact they probably are quite busy, but the to-do list does not shrink. Having many projects partially finished is far less productive than banging out tasks to completion, one or two (or when necessary, a few) at a time. In the agile software development community, limiting WIP is a celebrated attribute of employees and teams.

According to lifehack.org, no one can be too busy if they prioritize properly. Lifehack contributor Conor Neill writes, “if you have 3 priorities, you have priorities. If you have 25 priorities, you have a mess.”

But how can priorities be rearranged? Sometimes, there is just a lot to do.

Author Gary Keller recently wrote “The One Thing,

a book about how if you can identify the one thing that you can do that will make everything easier to do, your productivity can soar. What One Thing stands between me and a productive day? Or, what One Thing can I get out of the way, learn, achieve, etc., that will exist in harmony with the other things on my list, making everything that much easier?

Identifying that one thing leads away from WIP and directly to productivity.

Reprioritizing goals can often be connected to that “one thing,” but it is also a heavy-hitting tool in the attempt to limit WIP. If I say “yes” to too many things, surely my brain perceives that they are nearly all of equal importance, and I try to attack them all, but I am setting myself up to fail. I will be busy, yes, but I will not be productive. The skill of saying “no” to some activities, tasks, or events is a difficult one to master, particularly for those of us who have families – or even dogs. The desire to keep everyone satisfied, from partner to kids to Rover, is a strong one. Warren Buffet is credited with saying that the definition of integrity is that you “say no to most things.” Hey, there is a reason those pro/con lists were developed in the first place!

im-too-busy Another aspect of busy not equaling productive is that busy people tend to tell you how busy they are. Feeling productive is not the same thing as actually producing, so just the action of being busy does not, cannot, suffice. When we want to really accomplish something, we make time to do it. We focus on the task at hand, make it important, and grind it out – sometimes to the exclusion of other things. And that is just fine. Action supports production far more than words do (unless you are a writer, in which case the words are important – but not the words, “I’m busy making excuses for not writing because I am too busy!”

In his book, The Path to Extraordinary Productivity, Gary Kogon claims that people have gotten far too proud of the sensation and claim that they are busy. Inc.com visits this in their Inc. Video, “Productivity Playbook.”

Barbara Hemphill, of the Productive Environment Institute, has exceptionally good advice for remedying the “busy” out of our productivity. She claims that while busy people have very long to-do lists, productive people carve out the three clear goals of the day, and write those down instead. Hemphill insists that “if you consistently do not get those three things done, then it’s time for some serious conversation with yourself.”


She recommends that in order to be truly productive, we should return to (if we ever were there) “single-tasking” as a way to remove ourselves from multitasking. (Back to that WIP idea, here we go.) By limiting the day’s prioritized tasks to three, we are more likely to stay on task and not allow distractions to sway us off course. The end result? Results. The ability to say, “I did X,Y, and Z today” instead of lamenting that A, B, and C are still on our task lists.

The takeaways? I think there are a few. Learning to manage time productively is more than just good time-management. To be truly productive, we have to show that things were completed. An author talks very little about what she is writing now, but is super-proud of what was just published. The complete work is the thing.

So in order to do that – Limit the number of tasks we take on.

Prioritize the tasks we agree to

Agree only after considering “no” as a viable option

Remember that there is no prize for being busy, but there are                                                          rewards for work  completed.

So now, I suppose that in order to cross one item off my three-item list, I should now hit the “publish” button and send this one in. Tomorrow I’m going to be really busy…No, but I AM going to be very productive!



Why Developers Make Really Bad Tech Writers



Every now and then, I come across a blog post or other article or column declaring that technical writing for software development is a dying career, lamenting that all of us in the tech writing game should plan our exit strategies and admit that if a product is truly well-designed, our services are simply not needed.

Surely, in some product cases this is true. However, in many high-level software instances, I defy you to successfully install and run the product without some help from your friendly neighborhood tech writer. I pose this challenge because developers think and behave like developers and users think and behave like users. There is a chasm as wide as the English Channel between developer and user, and only the talented technical writer can provide transport safely across.

It’s not that developers are incapable of writing well or that they cannot write documentation, and it is not that users cannot ferret their way through intricate software. Developers could write supporting documentation – IF they weren’t developing that particular product. But alas, developers are too close to the products they are developing. They lack adequate perspective when it comes to their fledgling software, and they have great difficulty seeing it from a user’s point of view. The software, to a developer, makes sense. Developers arrive at a use-stance with some assumptions about functionality and behavior already in hand. So they make lousy content writers because they can’t see it from a user standpoint.

A shift needs to occur in order to artfully create usable content. A developer’s view is, “this is the product, and here are its amazing features,” whereas a technical writer will approach the very same thing from a perch saying, “here is how to do some amazing stuff with this new product.”

Technical writing shifts the focus to a user-centric view that is very difficult for a developer to take. It’s also no small thing that technical writers have been trying to master language, grammar and syntax for the better part of their educations. It’s a sure bet that developers have taken English courses as part of their college education. There are no programmers out there who are illiterate, don’t get me wrong. I work with some really smart people, no doubt about it! But when I tell them that all of our documentation is better perceived in active voice rather than passive, I tend to get a room filled with glassy-eyed folks who really want to get back to their work creating dynamic rules instead of determining whether or not they need a helping verb.

Technical writing in the software field is far from dying. What it IS doing is merging – tightly – with user interaction. It is absolutely, inarguably true that users wish they did not have to read so much in order to get started when they have a new product in their hands. So when we design documentation, we had better design it to work well. Lean documentation is essential – Strunk and White and their mantra “omit needless words” were not kidding.

Working with developers is an art. Letting them do what they do best, and making way for what writers do best, is a science.

I’ve argued more than once that mastering a given tool, like Dita or Framemaker, is fruitful but only if the situation calls for it. I have a totally separate set of tools that I use in my job, and they may or may not prove to be portable, but the skill that is 100% portable is that I can talk to, work with, communicate with, and understand – developers. I let them do their jobs with great enthusiasm, and I encourage them to let me do mine. It’s a synergy that keeps us all smiling, and pushing software out the door at a high rate of success. I work on UX, I design good doc, I focus on usability, I listen to my data.  I look at those sills that simply crackle with career stability. I let the developers tell me everything else that is important. And…I don’t make them write too much. Why? Because they don’t really enjoy it anyway.

And developers make really bad tech writers.

At the Corner of Gridlock and Unlock

Lily Tomlin did a great character in her film, “The Search for Signs of Intelligent Life.” The character was Trudy, the bag lady. Her monologue has been repeated by amateurs all over, but I wasn’t able to find Tomlin ever repeating the scene.

(This one’s pretty good.)

The monologue has alternately been dubbed “Standing at the Corner of Walk and Don’t Walk.” It’s that good – it has its own monologue name.

My home city of Pittsburgh, PA, is at its own Walk/Don’t Walk corner right now. We are at a better corner than a schizophrenic, convinced she once worked for a snack dynasty, though. We have an infrastructure problem to solve, and we just might get a whole buncha money to help solve it, and the technical expertise of Google’s mobility program, Sidewalk Labs to help us do it.

What’s at stake?

Well, as Sidewalk sees it, there have been some pretty big revolutions (three, to be precise) in city-building, and those revolutions have come at a high cost. If they can develop a more cost-effective and efficient solution to the sure-to-come fourth revolution, it will be…well…revolutionary.

steam engine

According to Sidewalk Labs, we first moved people around and developed cities thanks to steam. (Think locomotives!) That makes perfect sense when you think about Pittsburgh – for crying out loud, we wouldn’t have any trains and train systems if it wasn’t for steel, and steel is the very industrial backbone of Pittsburgh. (Hello? Our football team is even named the Steelers!)

Then came electricity, which granted us lights for interior spaces, which is also a darn good thing for Pittsburgh because with all that coal dust and smoke from the steel mills, we sure needed electric lighting. We even needed it to light the interiors of the steel mills, but probably more importantly the homes of the likes of innovators Andrew Carnegie, Andrew Mellon, and Henry Clay Frick, who paid for most of the development of the steel industry and the urban development anyway, despite the many controversies surrounding their methods. Remember that guy who said Pittsburgh was like “hell

hell lid
Pittsburgh, 1872

with the lid off?” (For the record, it was James Parton, a writer from Boston, who penned it in 1868 – we still don’t like him.)

So electricity is the second revolution. Then along comes the automobile. That’s a major issue in establishing urban living, to be sure, and if you haven’t seen Pittsburgh’s topography, you can’t possibly appreciate just how revolutionary the automobile is to comfortable urban development.

We are a city built at the confluence of the Allegheny and Monongahela Rivers, which places us in a basin of sorts, carved by mighty rivers, flanked by mountains which are gorgeous but steep and majestic, necessitating roads that wind, angles that astound. Pittsburgh as a city maintains 700 sets of “City Steps.” These are cool, essential components of a pedestrian infrastructure connecting neighborhoods that are steep, and which would otherwise have impassable vehicular connections street-to-street without winding a mile or more.

The steps are great, but without a car to spirit you over Mt. Washington or across the mighty rivers, you’d be stuck living along the rivers in what we lovingly call “the Golden Triangle,” and that would leave very little land to develop into the beautiful urban spaces we now have as both the North and South Shores.

Instead, our city planners and companies like Sidewalk Labs see a fourth revolution on our vista, and it’s a digital one. We already know that things like crowdsourcing apps (think Tiramisu) can help us transform transportation and smart living (think Wink) can integrate into our daily lives, but can they help our daily commute in ways that truly make us more secure, solve our most pressing problems as a city, make us safer, respect our privacy, and bridge the gap between city of today and city of tomorrow?

It seems like that is what they wish to set out to do, and since Alphabet-style (nee Google) minds and energy levels are behind it, I wouldn’t be the least bit surprised that the rate of success feels quite high.

I’m looking at just one idea for now – it’s their notion of Flow.

Sidewalk Labs sets out to wrestle congestion. I’m an avid cyclist. I still harbor a bit of fear in city cycling because, hey, people get killed on bikes. It’s real, and it’s scary. It’s expensive to commute, though, and I love the environment, so if I could be a part of a solution to the rat-race commuter congestion issue, I’d sign up in a heartbeat. Flow analytics with Sidewalk Labs is looking at Pittsburgh as one of the finalists in a 7-city competition to use analytics and messaging to increase efficiency of roads, parking and transit. That is our Walk/Don’t Walk. Can we move from being one of Seven Finalists to being “the one?” Will Pittsburgh get the final rose?

So I’m asking myself, “Hey, as someone who wants to be able to bike around the city better, how will this help me?” And my answer was easy – if there is less congestion in general, I get back and forth safer, and the mobility issue in general is an improved experience. Win-win-win. Drivers and cyclists together are happier people. Mayor Peduto has been working hard to integrate better, safer bike lanes in our city, and although not all of the data is in, the results so far are pretty great. More bike commuters, with happier faces, and very little (if any) added congestion in our downtown corridors.

They have this interactive messaging (this is where the tech writer in me totally geeked out) and dynamic parking (woah) along with dynamic transit (everything green and eco-friendly about me went berserk now.

So here’s the gist of why this tech writer went all off-topic and posted about an urban-development app on a Tech Pub kind of page. This is the sort of thing every city should get behind. This is the kind of Justin Trudeau, Portland-can’t-beat-this, nobody can oppose this idea kind of stuff that makes cities great. This makes life great. Who doesn’t want a smoother commute every day? I mean, unless you already work at home in your pajamas and only have to walk to the grocery store, the dentist and the veterinarian, this seems too good to be true. And when this thing happens to be available near you, do the work. Participate in the data-gathering, because this is not big-brother in the way that some folk might cast a side-eye toward. This is the stuff dreams are made of. Beautiful, blissful, traffic-jam, I found a parking space dreams.


Pittsburgh, 2015 – We are much, much cleaner than Hell now!



International-Womens-DayI know I just posted yesterday, but I have had a working draft of this piece in the hopper for a while; it just never quite grew its feet, as I like to say. And I can’t put a piece on the blog until it has its own feet. But today, being Women’s Day and all, the piece found its feet.

I recalled Isis Anchalee – remember her? She’s the bright, talented, strong, and yes, beautiful platform engineer from the Tech Startup OneLogin who asked her to participate in their ad campaign, which then sparked the #ilooklikeanengineer hashtag movement. It didn’t take long for the misogynists among us to determine that Isis was simply too pretty to be a “real” platform engineer. There’s just no way a smart brain could be housed in that attractive body.

The movement caught on fast, but it has faded just as quickly. It’s not enough to repeatedly have lists like Forbes top 30 women under 30, although that’s a great list. I say it’s not enough, because when a company like Microsoft reveals its diversity numbers to reflect the staggeringly awful truth: over 75% male and 60% white, with an only 29% female workforce globally, that’s alarming. And then comes the real hit: only 12.5% of Microsoft’s senior leadership in America is female. (Source: Forbes). This is happening even though we know that women are generally better at coding tasks than men.

But we also have to reveal the truth that, according to the US Department of Labor, only 12% of Computer Science graduates today are women.

Why? What about this environment is blocking women? Are we really just not cut out for this field?


Not really. According to Gayle Laakman McDowell, author of Cracking the Interview, and a coder herself, it’s primarily that girls, when they are girls, are mostly sent the message that, “hey, this stuff is not for you.” Subtly or overtly, young women are, from a very young age, steered toward the humanities while young men are steered toward hard sciences. (We’ve known this for a long time, but I’m providing ethos here. I’m a writer, so to show you I have backup, I provide a subject-matter-expert, okay?)

So we tell girls and young women that they just don’t look like coders. They look like teachers, they look like nurses, they look like bank tellers or whatever, but they do not look like they fit in the cubicle-hive style pressure system that is software development or platform engineering. Is that it?

In other areas of their lives, we are telling them to be “totally natural,” or to be proud of what they look like. We tell them to embrace their body types and to live their lives with gusto. Kate Winslett recently signed a modeling deal with L’Oreal that has a “no Photoshop” clause, and we applaud this honesty and truth to herself.

But we haven’t told young girls that if their true beauty is in writing code, that they are totally entitled to that gorgeousness?

The percentage of women who work in tech companies remains consistent, at around 30%. So there ARE women who do this stuff, but it’s stagnant. It is failing to grow. Even though more women go to college, and an even greater number of women attain graduate degrees, the percentage stays flat. Now, what I find truly remarkable is that the percentage of women in technical or leadership roles – roles where they can actually influence the direction the company takes, is even lower. This difficulty may be the result of well-known sexism in the technology sector, or at least an unwillingness to combat it. The New York Times ran a great piece in April of 2014 called “Technology’s Man Problem,” documenting just this trend, and not much has changed in the last two years, but some things have.

It is not just a matter of moving more girls into a pipeline of studying STEM, because the high rate of attrition in tech moves them right on out the door just as quickly. Teaching women and girls that the tech field is appealing, lucrative, and open to them is not the quick fix we hoped it would be. Instead, fixing the culture that says, “you don’t look like an engineer, coder, tech writer…” THAT is the solution, or at least part of it. In the UK, a campaign called “This Girl Can” strives to connect young women through physical activity and inspiration, while here in the US, Target recently launched an ad campaign called Target Loves Every Body.

I believe we need a culture shift that defines, or redefines, the landscape to show that coders look like lots of things, and writers look like lots of things. Women in many careers have been trying to reshape their images from Hollywood to magazine covers, so why not in Silicon Valley, too?

Women helping women is the key to confidence and the key to success. If tech culture is going to change, everyone needs to change. The emotional and professional cost is simply too high not to. So on this, Women’s Day, the challenge is to reach out to a woman in your field – or a woman not yet in your field – and mentor or inspire, encourage or reassure her. That is how it gets done. Make a pledge to yourself that you will make room in tech for one more young woman, or that you will make additional room for one more established woman. It’s a jungle in here. Even women who have worked in here for years can get lost in the tangle of tasks, so have lunch this week, next, and next month too. There is networking to be done, and we could all use it. Today does not need to be the only Woman’s Day you have this year. Let the women in your life, especially in your tech life, know that they LOOK like accomplishers, achievers, builders, and leaders.

And then, if you are a woman, make sure you accomplish, achieve, build, and lead.


I Like the Ambience in Here


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) aamazon-echo-dot-lit-upnd 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?

Wanna Be?


What makes you want to be a technical writer?

I recently saw a (rather poorly written) post on this very topic. It’s not a big mystery, why people go into technical writing, and yet I see posts that are similar to this all the time.

Oooh, why would you go into technical writing? It seems boring. Isn’t it dry? You seem so creative. You should write poetry. Don’t you write fiction, too? The answers are pure, they are simple; they are common. Anyone who varies too greatly from these is either naïve or lying.

  1. I am a technical writer because the job is fairly secure. While the world of creative writing is fun and soul-filling, it is as secure as acting or ballet. There is no guarantee of a paycheck next week in the creative and performing arts. So, while my BA is indeed in creative writing, and I think I am fully capable of writing the Great American novel, I am just a tiny bit risk-averse. My MA is in Rhetoric. So, I ply my trade week in and week out by putting as much creative spin as my company allows on the technical prose of mainframe computing. In my extra time, I blog. I write flowery emails. There you have it. Technical writing pays the bills. It allows me to be a professional. Mystery solved.
  2. I am interested in the field. Let’s face it, even if I believed and professed all of the things I’ve written above with my whole heart, if I lacked interest and acumen in technology, I could not write about it. I’m fairly certain that the greatest poets in the world could not be successful technical writers, because they lack an interest in what I do. One of the things that I believe landed me this job was the ability to discuss, articulately, topics like the internet of things, chunking, and what I would do if I simply did not understand how a software program works. I conversed in SMEs and design documents fluently enough that my interviewers saw that I was willing to work through problems and learn new systems. I don’t know if Salinger did that.
  3. I get to work with incredibly smart people. Sure, you could hear this in more fields than just technology, but this is especially true in technology. Many of the brightest minds work in tech fields, and that isn’t going to change any time soon. There are smart people working in real estate, hospitality, landscaping and a host of other fields, of course, and I am not set to disparage those careers in any way. But technology is a rapidly-expanding territory, which leads me to the last criteria for what makes me enjoy this field tremendously.keyboard
  4. I get to shape the language that shapes the things you use and buy and implement. I have insider information about the waves of the future. That new app? I get to hear about it early. The Internet of Things? That’s in my house. Indeed, I already turn my lights on with my cell phone, unlock my doors with an app, I use the internet to bank, heat my home and order food. I research driverless cars and automated delivery systems. But it’s not just toys and games. I learn about how medicine interfaces with human-computer interaction and how we are learning to send information instantaneously across continents. I design documents that can be read by machines and how diagrams can be interpreted in multiple languages and translated for those without sight. Some of this is job, and some of this is just fun for me.

I hope to integrate word strings so that one day a computer can do my job – the typing, not the thinking.


I am still very much an artist in the poetics and fiction and creativity department. I enjoy the artistry of the well-told tale, and I’ll never cancel my subscription to the New Yorker, trust me. But when you examine a vitamin bottle, or tap the box on the screen at the  ATM, keep a fond place for me in your heart, because odds are a chum of mine – known or unknown – drafted that prose. Demonstrating skill in the world of tech doc is a pretty fun gig when it comes right down to it. And you probably couldn’t install that version of your newest software if it wasn’t for a girl like me.

Who Reads the Doc?


I'm the tech writer

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 expladverbprotest_0071anations  (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 Bechdel Test for IT”


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 Funhomecovermusical, 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 gone with windabout 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 Apple computerfloppy 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.