Technical Writing

I’ve been a technical writer in software companies for a long long time. This is my attempt to explain what I do and make it exciting! I’m in the job market right now, so this is a necessary blog post (for the portfolio and all).

Here is my take on what technical writers do: we simplify complicated concepts so people can understand them.

Technical writers:

  • Use simple language. Occasionally I use big words, if they are just right. But mostly I use simpler words that more people will understand. This will probably always be my writing style. I think this habit developed when I was young and started learning words that other people didn’t know. It was easier just not to use them, trust me.
  • Are allergic to jargon. Acronyms and arcane technical terms set off my antennae. If I don’t know what something means, chances are the average user won’t. (In the tech world, “users” are the people who actually use the software after it’s bought. If they need to read manuals or use help, chances are they won’t know the latest jargon.)
  • Are logical and a bit OCD. I have a different way of thinking than engineers, because I need to make lateral leaps to condense information. I’m fond of trying to find metaphors and running with them until they don’t work anymore, which is very annoying to some literalists. But, I do need logic to ask the right questions so I can explain things step by step. I like using numbered lists to do this, and making sure topics follow along rationally. I like to order information just so (that’s where the OCD part comes in).
  • Ask, “What would a person do with that?” and other “dumb” questions everybody is afraid to ask. People writing software often work in a small area of the code, so may not have time to think about the big picture or “the user experience” (how users actually use the software in real life). Sometimes there are team members who can explain everything to me (Yay! Love them!) But sometimes everyone on the team is stumped and I need to avoid explanations entirely. I’m not proud when that happens, but it’s not literature I’m writing and there are deadlines.
  • Are sometimes the canaries in the coal mine. If everyone has worked on their little piece of the project and nobody has tried to put it all together logically until the writer comes along, my job is sometimes to say “This isn’t making sense.” Occasionally I uncover a flaw nobody thought of. Sometimes I have to squawk about how I just don’t understand it at all. Luckily not often.

Fun fact! In French, technical writers are called “vulgarisateurs” or “redacteurs.” I’d like to be called a redactive vulgarizer, it kinda makes me feel badass.

Technical writers, like many others in the software industry, can suffer from burnout. It is really easy to start feeling defensive, especially if you’re the only one asking the dumb questions every day and people are too stressed to answer them. As well, we have to accept that our thousand-page magnum opuses (aka manuals) will be stale within a couple of years because technology changes so quickly. With the Internet, I guess we are no longer alone in this. Words have become a giant data storage experiment, and should all have a best-before date given the rapid change we all are going through. (They are stored “forever” though—that is a topic for another post.)

I’m up for being a cheerleader though. In the current age, I’m excited to be engaged in finding clear explanations, with a dash of vulgarization thrown in to get at the big picture. I have come to realize that words create change. If you explain something well enough for people to grasp a new idea, it means that idea can take flight. “What would I do with that?” is a question that has been asked throughout the ages, probably starting with someone wondering why someone else was rubbing two sticks together. The answers to that fundamental question have driven human innovation to astonishing levels.

Thanks for reading to the end. 🙂


I saw a guy in my trendy neighborhood rocking the perfect woolly black beard, sporting a black t-shirt emblazoned with one word in white all-caps: AVOIDISM. What a perfect word to describe just about everything these days, I thought.

Avoidism is so easy now. If somebody posts something we don’t like, there are tools to make sure we won’t see it again. It’s as simple as clicking the “Are you sure you want to block this person?” button. Poof! The icky ogre is gone.

Avoiding the icky extends to just about everything. Funerals are memorial services (“No icky dead bodies!”). News is curated (“Just give me what I want to know, no ick”). Nature is mono-cultured, with pesticides to rid us of all those pesky insects (“Insects are icky!”—I’ve known people like this). Meat comes conveniently packaged in pretty plastic packaging (“No icky feathers or fur”). I’m not saying any of this is right, but this is just the way things are, right? Avoidism is so … convenient.

I have to confess I’m as skilled at avoidism as the next person. I rarely bother with news stories I don’t want to hear. I cross the street to avoid “problematic” people. I avoid meaningful discussions on politics unless I trust the person I’m talking to is on the same page as me, so it won’t get all shouty. I’m not proud of any of this, but avoidism is a survival strategy. And it seems a lot of us are infected with the zombie avoidist bug where our desire to engage has been fried.

So what do we do to re-engage?

I could quote the Serenity prayer:

God, grant me the serenity to accept the things I cannot change,
the courage to change the things I can,
and the wisdom to know the difference.

And yes, this resonates. We should try to recognize what we can change and go for it, and not be foolish enough to beat ourselves up trying to change things we can’t. But I find this prayer insufficient. “Too problematic,” “Out of scope,” “Outside customary parameters,” “Not this department’s responsibility,” “Too many variables to include,” “Beyond normal risk tolerances,” “Needs further study”—our language is full of avoidist patterns of thought, serenely spoken, delivered with the ingrained wisdom that things cannot change so there’s no need to engage. But we all know things need to change.

So what do we do?

I recently read an article about Hillary Cottam, a British thinker and “social entrepreneur” renowned for her way of finding simple answers for difficult social challenges. She’s really engaged in things.

When she was at the World Bank, Cottam avoided the 5-star hotels and went into the field to figure out what they actually needed to make their lives better. In Zambia, she recommended a central pump (not a $140 million dam development as proposed). In London, she figured out that children weren’t settling down because their lockers were in a bully-infested dark corner of the school. By moving the lockers, bullying went down and academic scores went up. These sound like straightforward solutions, but it took lots of engagement to cut through the obstacles and make them happen.

So Cottam is an inspiration that there are simple solutions out there, and the people most affected already know the answers, if they spoke up. So maybe the Serenity Prayer still applies, but we need to focus on the words “courage” and “wisdom.” The courage to ask questions, imagine solutions, and speak up with the answers.

Alas, the article I link to above is negatively positioned as “There’s an idea that could transform Britain – but Brexit won’t let it be heard.” What a downer! But I found the mention of Cottam inspiring nonetheless. She is proof that there are people out there engaged with finding real solutions to real problems.


CN Tower in fog

It’s a human trait to torture ourselves with what we aren’t. Let’s call it envy. And I confess that I work really hard to suppress envy. It still creeps up on me when I compare myself to others and find myself wanting.

It goes like this: I wasn’t old enough (then too old). Not rich enough. Not forceful enough to be a high-powered Master of the Universe (and if we aren’t a Master of the Universe, then what are we?) I wasn’t muscly enough, then too muscled to be in fashion, back when skinny arms were a thing but maybe muscles are back in style again so am I OK now? You get the picture. I won’t go on … I don’t want to share ALL of my insecurities and I’m sure you don’t want to listen. 🙂

Then along came Instagram, and for a while my envy got even worse. That platform is designed to be a giant envy machine. If you feel remotely good about yourself, just go there and it’s guaranteed there will be somebody more ripped than you, certainly younger than you, traveling to gorgeous places, eating wonderful meals, and wearing all the right clothes. In short, it’s really easy now to feel crappy every day by envying other people’s images. Social media is designed this way and has created a whole new set of people called “Influencers” to do this to us.

And yet, maybe this whole Influencer overload was a good thing for me. Maybe through sheer overexposure it’s helped me understand that I don’t have the energy to compare myself to others all day and stay true to myself. Maybe I have finally learned simply to say, “That’s nice. But it’s not about me.” I can still admire people for their accomplishments. Why not? Influencers work really hard. But admiration doesn’t have to be envy.


If you admit to a wee bit of envy here and there, read on. Here are some things that help me overcome envy (on my good days).

Know yourself. Love yourself. See my previous posts. If you become your own best friend, you won’t be beating yourself up comparing yourself to others. If you are comfortable in your own skin, envy can’t take hold. It isn’t easy. It’s something to work on all the time. There are so many built-in traps against self-acceptance. But when you catch yourself envying others, stop and be gentle on yourself and remind yourself it’s their life, not yours.

Empathy. Everyone out there is trying to put on a good show. If you recognize that and feel for their efforts, if you humanize them, it’s way easier to see that their path is not your path, and their path indeed may be just as difficult (or more difficult) than yours. Six pack abs, when you’re no longer 28, take a lot of work and probably mean you’ve given up something else. Same with most successful people: they have made sacrifices to get there, and you chose a different path. If you try to understand a bit of what is motivating others, you may become more aware of what is (or isn’t) motivating you.

Laugh. Laughter is more fun than envy. So don’t take life too seriously. I don’t mean being cruel to people and making jokes at their expense (see empathy above), but we have to acknowledge that people go to some pretty hilarious levels to impress others. Whether it be $10,000 Gucci purses, or 0% body fat, or outrageous bear-baiting statements for the lolz, or hanging out of moving trains to take selfies … you gotta shake your head at some of the antics people use to get noticed. You don’t need to go there. Just have a chuckle over it.

Get busy doing what YOU want to do. I’m now busy chasing my own dreams, so have way less time to envy. Start doing the things you want to do and the things you are proud of doing, and you won’t have the time to envy others. You may not even have the time to hang out on social media for hours feeding your own insecurities. It’s working for me!

You may be one of the fortunate ones who is comfortable in your skin and never envied others. But if you’re still reading this, I bet you’re in my recovery camp. Whichever camp you are in, it pays to beware Envy. It will sneak up on you at any time. It may no longer be considered a sin, but it does mess with your mind and take away from your dreams.

Know Yourself (2)

In today’s social media storm with all its outrage and proudly held opinions and manic disregard for facts, we all need to develop a really strong sense of who we are. If you don’t know yourself and where you stand, it’s really easy to drown in a murky sea of fear and anger and emotional overwhelm. It seems the world is designed that way right now.

If you don’t know yourself, you can’t know what your passions are, and what your dreams are. You will feel powerless to create the change you need to grow. Isn’t it time to carve out the time to be with yourself, to ask yourself the questions that matter, to figure out the dreams that speak to you?


I won’t lie. It’s still really easy to lose myself, to float away in worry or dread as I stare too long at Facebook or check the news sites or look at my Visa bill. But I’ve developed a few techniques to keep myself better grounded and centered, and I’d like to share them.

Quiet your mind. Our brains are not meant to be processing all the time. We need to turn off our brain sometimes so it can “reboot”. So we are better able to process all the possibilities. So we are better able to dream. Good sleep is the essential component to keeping the brain healthy, but not the only one. I try all kinds of techniques to tune out the world so I can tune in to myself: yoga, meditation, biking, gym, walking, hanging in my garden, cooking, even cleaning.  Whatever works for you, as long as you’re letting your mind rejuvenate and refresh, away from worry and the daily grind and the bad news. And note well! Kicking back with your phone or iPad definitely does not count because you’re just keeping your mind overwhelmed with other people’s thoughts. You’re outsourcing your brain to them. Being online is not quiet time, it’s intense mind overload time!

Be easy on yourself. If you beat yourself up all the time, you are too preoccupied to dream. You are too preoccupied to even know how to dream. So just stop with the “shoulds” and “can’ts” and “I’m not good enoughs”. They are not helping you. It needs a whole separate blog or five to begin to tell you how I started to figure this one out. It was a personal journey. Of course RuPaul had it figured out already:  “If you can’t love yourself, how the hell you gonna love somebody else?” Let that sink in.

Weigh the advice of others. People are really good at giving advice, and can be a really good mirror to show you how you’re spinning your wheels or sabotaging yourself. A word of caution, though: you can easily give away decision-making to others. It is your responsibility to weigh all advice and decide if it makes sense for you and your situation and those around you, and act on it appropriately. Find a place of calm, place your hands over your gut if that helps, and ask, “Does this fit?” When your gut tells you that someone’s advice doesn’t seem right, accept their advice with grace and then just file it away. It may be relevant later, it just isn’t right now.

Have faith. I don’t mean religious faith here (although if your religion empowers you, that’s great!). I mean trying to go beyond the “I can’t” or “I shouldn’t” and daring to dream that anything is possible. No matter how bad the situation seems, you won’t fix it by saying “nothing can be done” or (one of my least favorite expressions) “it is what it is.” If it’s something you want to change, change it! If it’s something you want to create, create it! You have the power to make something brand new if you dare to dream, and if you want to put in the work to make that dream a reality.

Journal. This year I started journaling every day. It’s kind of magic. I write down some of the nonsense in my brain—the doubts and frustrations and fears and anger—and then, usually on the same page, I’ve figured out the answer. At least, the answer for today (which is all we need to keep moving forward). My journal has become such an important part of my work on myself. It’s a way to turn “I can’t” into “Let’s do this!” I realize journaling won’t come naturally to everyone (I’m a frustrated writer, so it’s brilliant for me). And for some people–artists and musicians, for example—there are other forms of creative expression tailor-made for them. I’d still recommend journaling for everyone though. Words are perfect tools humans use to explore most every part of the human condition, and have great power to change our thoughts. Use them to create your own magic!

Those are a few things I’ve used to get to know myself. If you feel you don’t have the time to do any of this, don’t beat yourself up about it (See “Be easy on yourself” above). Even if you take just 5 minutes a day to check out and tune into yourself, that’s a start. Dare to dream. We will change the world for the better with our dreams!

Know Yourself (1)

“Know yourself” is a maxim that dates back to Ancient Greek times. And in today’s crazy world it’s more important than ever. The world is moving too quickly now to just tread water and pretend we are OK. If we don’t know ourselves, we leave ourselves open to others telling us who we should be. We risk being swept away.

Some people may not yet feel the need to know themselves. They may say, “Of course I know myself! I’m here!” Or maybe, “Why do I need to do this navel-gazing when I can just be doing things?” Or maybe, “Why is it important? I have others to tell me what I need to do!” Or maybe, “As long as I make money I’m good!” There are lots of easy ways to avoid self-knowledge.

And the meaning of “know yourself” has also changed, at least for me. I used to think it meant choosing a profession, the “what will I do when I grow up?” question. By this measure, I felt inadequate. Other people “knew themselves” from an early age: they knew they wanted to be lawyers or doctors or actors or musicians. But I like most people wasn’t so sure what I wanted to do, and told myself that what I really wanted to do was impractical, not easily monetized. So, by the “what do you want to do when you grow up?” yardstick, I felt I was a failure in the “know yourself” lottery.

Finally, I have figured out that “doing something” is no guarantee of knowing yourself. In fact, if we keep too busy on things that don’t matter to us, it’s really hard to get to know ourselves. It’s avoidance. To know ourselves is to know our values, our strengths, our limits, our passions. To know ourselves is to filter out what’s not important, and zero in on what is important. To know ourselves is to know our dreams so we can go after them. It’s constant but rewarding work. As we grow, there are more and more ways to know ourselves in all our complexity – and go after our dreams unapologetically.

Here I Am

My first blog post. (Deep breath.) I’ve been thinking about blogging forever. I put up a technical writing blog site over 6 years ago, but bots brought it down. I had a full-time job and didn’t feel the need to start it up again, and then the world went big-time crazy and I wondered why I would ever want to put myself out there anyway. But the stakes seem higher now. It’s time I spoke up. It’s time we all spoke up.

This blog will not be focused on politics and grand opinions about how to save the world. That’s not to say I keep my head in the clouds. I have STRONG opinions on lots of things, and can fall into fits of despair at how insane it all is. I admire the warriors out there who are speaking up and trying to stop the insanity. Fight on!

For me, I find that dwelling on the negative and on anger draws me into pointless battles, keeps me preoccupied with insignificant arguments, works me up and wears me down. Then I need to check out, lick my wounds, get centered again, before I re-engage.

We all need to get centered again, and that’s what I want to focus on. We need techniques to heal our wounds quickly, so we can get back out there. And the biggest part of it is simply learning to be OK with ourselves. When we learn to be OK with ourselves, then we can work magic on others and on the world.

I’ve mapped out some survival strategies that have helped me, and will share them in future posts. I don’t claim to be an expert on how to sort out anyone’s life (even my own). But I have discovered that all of us (me too!) must speak out with confidence and listen to others with empathy. I hope some of it resonates with you.

We each have our own journey, and parts of that journey are lonely and hard, yet so rewarding if we stick to it. That’s why I take the road less travelled.