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.


Mark Zuckerberg’s Gift to Women



We all know Mark Zuckerberg’s gift to the technology sector; we all have (or had, or will have) Facebook accounts. Social media is a universal connector. With Zuckerberg’s recent announcement that he will take a beautiful, wonderful four month paid paternity leave, he casts into bright light the issues of family and work-life balance in the technical industry in ways that women have hungered for for decades. According to the Wall Street Journal, the Facebook Founder has recently announced that the benefit will extend to all Facebook employees. Facebook has joined companies, many in the technology sector, in expanding parental leave benefits, and including fathers and same-sex partners. Why is this a huge boon for moms, though?

According to the Center for Talent Innovation, women are far more likely than men to leave their jobs in science and technology despite the fact that we all know that jobs in tech – especially in computer science, Zuckerberg’s very wheelhouse (and mine) are projected to grow up to three times faster than other STEM sectors.


By declaring that his family must take a central role in his life in order to create the balance that he seeks in order to succeed, Zuckerberg has sent a shining beacon to every industry – not just tech, although this is significant for us – that such balance is essential. He is doing for men and women what we have only dreamed of in the past.

Now, before you think I am merely shouting for women’s and mothers’ family leave, I know that the U.S. still has great leaps to make in terms of addressing gender equality, and there remains a huge gap in the general gender imbalance in the tech industry at large, but here is where I see his move making a difference:

It may be that very few traditional men will follow his lead, but more women will feel comfortable establishing the primacy of their maternity leaves. But given a little time, men will take the lead. And partners will follow suit. And fewer mothers will feel obliged to behave like the Melissa Mayers of our industry, or at least fewer will feel pressured to do so. We already know that it is important to calibrate our lives to find balance, it’s just that we rarely know how to do so. I don’t want to cast aspersions on Yahoo’s Melissa Mayer, because frankly, shaming one another about our mothering decisions is SO 1990. It’s time we get over that. Enough, already. That’s not what I’m trying to do here.


What I’m trying to do is to say that there is room for everyone at this table. I, for better or worse (I’d like to offer the opinion better here, if only because I now hold not one but two Master’s degrees, and my kids are awesome) jumped off the career track to raise my kids as a SAHM for a decade, and I loved it. During that time, I had a cottage soapmaking business, I ran the PTA, I volunteered tirelessly, and I never missed a school function. My choice. I gave up on a great many things, including stylish clothing and intelligent conversation with adults. What I did after my kids were school-aged is rev up my engines and jump back on the career track, never apologize, and here I am now, in a job I enjoy, fast-tracking myself personally and professionally. Melissa Mayer is choosing to spend fewer than her company’s offered maternity leave and instead heading back to her office a mere two weeks after what will hopefully be an uncomplicated labor and delivery very near the holidays. She is instead opting for what she calls “hard work and thoughtful prioritization.” We can hope for the best. Every family chooses the path that works for them.

Susan Wojcicki, the CEO of You Tube, wrote about this in the Wall Street Journal recently. Her own maternity leave, taken five times, “gave me a broader sense of purpose” and “a better ability to prioritize and get things done efficiently.”  Another specific benefit of this time that Wojcicki realized is one that Tacy Byham, CEO of Development Designs International pointed out at a fantastic networking event I attended recently (which I’ll have to cover in another post, because this one is getting too long). Wojcicki wrote that maternity leave “helped me understand the specific needs and concerns of mothers, who make most household spending decisions and control more than $2 trillion of purchasing power in the U.S.” Indeed. This is what Byham reiterated at the recent sitwithme.org  event we both attended in Pittsburgh a few weeks ago. Women, not the least of whom are employed women, control an awful lot of the spending in this country, and we are smart, informed consumers.

So let’s take a step back and review.

We need more women in STEM fields. Mark Zuckerberg just helped us open a big, giant door. We have examples of women leaders across the country, don’t we? So how did a dude help us out? Well, it’s simple, if you ask me. Twenty-one years ago, when I had my first child, I saw very little opportunity to effectively be both truly dedicated parent and truly dedicated to my job. I still think that there is a give-and-take that I perhaps would not be able to navigate. But I might be able to steer my ship more clearly through those choppy waters if I thought my partner could steer his ship, too. Alas! When parents can function as teams, when families can intertwine in such a way that it truly works – then we can truly work.

That may sound schmaltzy, but it’s true.

In addition to Tacy Byham’s great talk about women as leaders at the Red Chair “Sit With Me” event, I had the pleasure of listening to Debra Lam , the City of Pittsburgh’s Chief Innovation & Performance Officer. Debra was a dynamic speaker, and she really helped with the evening’s conclusion because she just had a baby herself – by “just had” I mean her son was one week old when she spent her evening talking with this group of women in technology. She’s that dedicated. One of her most salient points, though, was that while she is still on maternity leave, and she could have reasonably excused herself from the event that evening, she was able to be with us because she has the full support of her family. There are backup plans. Her family intertwines, and they get it. Her employer gets it. Her community gets it.

The city of Pittsburgh won’t lose a talented, gifted innovative woman in technology because we get it.

So thanks, Mark Zuckerberg, for making the conversation shift just a little bit. Even though we have a very, very long way to go, and these conversations need to trickle into every boardroom and every breakroom and every HR meeting and every hiring decision in America. I feel like you got it started.

You look very different from the guy who just wanted to get a date in the Social Network, that’s for sure.

I wonder what the Winklevoss twins think of you now?


Get Your Umbrella Ready – There’s a Tweetstorm Coming!


 In January 2015, a mere 11 months ago, Twitter’s founder, Jack Dorsey, endorsed the multi-tweet “twitterstorm” as a clever means of rapid-fire marketing. He wrote:


Dorsey also noted that tweetstorming was a pretty brilliant way to maneuver around the 140-character limit, and that it wasn’t the first time that users had built platform features that Twitter designers hadn’t thought of themselves.

In fact, it took Dorsey a series of 17 tweets to talk about his support of Tweetstorming. Charlie Warzel, of Buzzfeed, chimed in quickly with a response that Twitter’s newest trend was totally out of line and “Must Be Stopped.”  Warzel’s reasonable claim? Get a blog.

Dorsey not only lauded the notion of Tweetstorming, but also the introduction of video, photos, and other improvements like direct messaging and a mobile video camera. Many users cheered along with him. Conversing with a group, privately? Hurrah! Capturing and sharing videos right from your Twitter app? Amazing! The Twitter experience can now be full and rich. With just a few taps, you can add new dimensionality to previously flat and non-immersive text-only media.

By July, the concept and term had become popular enough, and had gained enough ground, that Twitter applied to trademark the word, “Tweetstorm.” No lie.

But, wait. What does this have to do with technical writing?tweetstorming

I cannot imagine the things it does NOT have to do with technical writing.

If I am now able to Tweet a set of user steps as a Tweetstorm, steps 1-12, for example in a series as simple as 1/1,1/2, 1/3 and so on so that users can see my Twitter handle and the steps they take, and I can imbed a photo or video along with what they need to do, or even use a screen capture of an on-site step, or a photo of the machine, the shop, the location or the outcome. I have now crossed over in real-time to becoming the most useful tool in the arsenal.

And if I can sit with a developer or support team member and walk-through the issue that a customer is having with the software we have developed, or I can be in the room with my Development Team and a User Experience Designer, a whiteboard and a Product Owner, and live-tweet the whole experience while we develop the documentation, then the medium gets the message.

This particular use of Twitter moves it from social to business and targets my audience with precision heretofore unimagined my Twitter, but that – in eleven short months – could be elegantly applied by businesses like agile software development in a global capacity with full force, especially by teams of document writers who may be located time zones away.

So, Charlie Warzel, while I sympathize that Tweetstorming is indeed not the proper forum for detailing your last evening’s date or repeating the behavior of the passenger next to you on the airplane, I caution that it may be that tech writers will co-opt Twitter in much the same way that thirtysomethings took over Facebook.

Better buy some gtweetstormeraloshes. There could be a heck of a tweetstorm.