Tag: technical writing

Working Remotely Worked For Me

Posted on March 31, 2016 by - Advice

I always wanted to be the kind of dad who was around for his kids during the day. I always thought, if it worked out, it would be great to work remotely. For me, one of the hardest things about having a full time job away from home was a feeling of missing out, of not being around, especially in those early years when my kids were toddling around. I’d see my kids briefly in the morning and then for a couple of hours through dinner and bedtime, full of reading, stories, and song. I valued the time I did have with them, but I always wanted more. Then, around the time my son was entering kindergarten, we moved to a different city and I took the opportunity to turn my permanent full time position into a work-from-home gig. This turned out to be fortunate, because my son’s undiagnosed autism led to a difficult transition to kindergarten. As hard as it was, I was able to be there for him and support him at school. I used to joke that I was my family’s chauffeur, given how much I drove everyone around.

The predictability of my work-from-home job gave me a solid platform from which to support my wife and children in the way that they most needed at the time. In the morning, I walked my son to school. In the afternoon, I stopped by after school to help him transition to after care. I worked in the in-between times. Because I worked with a team of writers that was also working remotely, this worked pretty well. I didn’t feel like I was the only one calling in to the office.

My colleagues and I experimented with several different tools to manage workflow (Trello and Asana stand out in my mind), but in the end we settled on a Google Sheet to track the work that needed to be written. I found the flexibility of my work to be quite freeing. I didn’t need to clock in for set hours, because it was more important that the work was done. Even though my work sometimes bled into evenings and weekends, I felt like I achieved a solid balance between work and family obligations. Not only that, it allowed my wife much greater flexibility in her job seeking process.

Unfortunately, about a year later my entire team was laid off following an acquisition. With a strong feeling that my son needed me to be around for him, I decided to pursue freelance work so that I could continue working from home. Little did I anticipate how stressful the hustle for work would be, nor how often freelance work would take me outside the home. But that’s a tale for another time.

My job situation is different now. My children are also older and don’t need my attention quite so fiercely. As stressful as it was at times, I’m grateful that I was able to be there, working from home, during some of their earliest years.

No matter what happens, I’ll always be there to read to them at bedtime.

How to Write Technical Documents

Posted on June 18, 2015 by - Advice

How to write technical documents first depends on the kind of technical document you’re writing. This is the biggest factor in deciding tone, style, word usage, etc. Most of the technical documents I write are user guides (UG), or Best Known Methods (BKM). Both types of documents save your reader’s time and energy, and can make the difference when launching a product or training session.

How to Write User Guides/Manuals


User Guides or Manuals (UM), tend to be longer, more complicated, and have more references. They generally deal with product specs, building instructions, and the like. The longest UG I have worked on was over 4,000 pages, the shortest are less than ten. They all follow the same basic steps:

  • Introduction
  • Body of the Text
    • Tools Needed (if applicable)
    • Steps (usually with Images)
    • Final results
  • Conclusion
  • Appendix with resources (if applicable)

Then it is up to you, the writer, to take all that information that you have tested, or have been given, and make it into something that the end user is able to read.

How do you do that? You KISS* (Keep it Simple, Scribe**). Think about who your audience is, a skill that is always important when writing. When I write, I imagine that I am producing documents for my grandparents or my friends who are ESL speakers (English as a Second Language). English is a tricky language, and a technical document is complicated enough without translation issues. Avoid turns of phrase and spell out all acronyms the first time they are introduced. Don’t take for granted the things that you know, they may not apply in a different language.

Another neat thing about writing UG/UMs is the fact that you can get away with publishing a whole document without a single complete sentence. In fact, bullet points, numbered lists, and notes are your friends in technical documentation. Bring on the sentence fragments! Use tables and images to illustrate the instructions. This is a situation where a picture is really worth a thousand words, and visuals are easier to understand.

When it comes down to it, the document is a more detailed version of “put the thing in the other thing and turn it on,” or some variation of that idea. If you can get that message across to the users, you’ve done your job.

How to Write Best Known Methods/Internal Processes


I find that BKMs are easier to write. Usually, when you’re writing a BKM it is for an internal process that you work on regularly. Examples of BKMs are: instructions on posting a document to an internal portal, how to run a machine, or how to process software testing. Even if it isn’t something that you work on personally, you should work closely enough with the person giving you the instructions to complete the final project. If you feel like you don’t have enough information, talk with your manager/engineer to fill in the blanks.

BKMs work best with clear instructions, small words (unless they are process specific), and diagrams. Think about trying to put IKEA furniture together without the diagrams. My house would be filled with nightmarish semblances of furniture. These documents are often shorter than a UG, usually less than ten pages. The writing process is very similar:

  • Quick introduction, less than a paragraph.
  • Steps for the process, including sub-steps, diagrams, tools needed, and images.
  • Conclusion/Summary of the final product.

Right now you may be wondering what the difference is between a User Guide and a BKM, which is understandable as they are similar. Think of a User Guide as the full explanation and possibly a little history of the project, whereas a BKM is a quick “how to.” Essentially, the two documents cover the same basic ideas, but the detail they get into differs. Remember: always keep your audience in mind. User Guides often go to external users (a wider audience) and BKMs tend to be internal (a smaller audience).

Final Tips and Notes


Technical writing is much like any other style of writing; you are passing along information to your readers in the clearest way possible.

  • Bullets, notes, and number lists are your friends.
  • Add images whenever applicable, the entire document can be images with minor text notes if that’s what works.
  • Keep your audience’s technical knowledge in mind.
  • Spell out acronyms the first time they are used, and consider adding a table of acronyms if the document contains more than ten.
  • Use tables to keep track of test results.
  • Don’t get fancy with your language. The document needs to be readable, not pretty.
  • Commit to a positive relationship with your engineers/testers, this will make your job so much easier. Tech guys tend to like cookies, just an FYI.
  • Most of all have fun with it. Even technical writing can be enjoyable if you keep an open mind. Proof-positive: I love my job.

*Tech Writers LOVE acronyms, seriously we can have whole conversations in them.
**Traditionally, this ends with Stupid, but I think that’s rude and ablest.

What’s in a Name? How to Choose a Title for Yourself.

Posted on December 1, 2014 by - Advice

“…that which we call a rose by any other name would smell as sweet…” Yes, but if you ask for a tulip and get a misnamed rose instead, you may be a bit disappointed. I don’t think anyone would dispute Juliet’s claims that a name, a word, doesn’t really get at the essence of a thing. Calling a rose a tulip doesn’t change the essential rosiness of the rose. There are even times, such as with Romeo’s last name, when the word for a thing can get in the way.

What do you do?

One of the first things that people usually ask is: “What is your name?” Followed hard on its heels by “What do you do?” These things are pretty tightly wound together, because I think when people ask “What do you do?”, they’re really asking “What additional name should I apply to you? How can I distinguish you between the other Shawns that I know?”

It wasn’t so very long ago that people tended to end up with surnames related to their work–such as Smith, Carver, or Cooper–or their relationship to other people–Johnson for John’s son and Carson for Car’s son. I think people still want the comfort of having a name for someone else that defines them, a kind of mental shorthand for thinking about and remembering other people.

What do I do?

I have lots of ways that I can answer the question: “What do you do?” I could say, “I’m a writer.” Unfortunately, this only conjures up a very vague and general idea of someone typing away at a computer somewhere, probably wearing glasses, like I do. I could say, “I’m a freelance writer,” in which case, the person might picture me at home, in my pajamas, writing away, perhaps with a cup of coffee. Ultimately, the answer to this question doesn’t matter too much when making small talk at a party, but when looking for prospective clients as a freelance writer, the name that I choose to describe the work I have done and will do is essential.

If I describe myself as a poet, then a client looking for a technical writer won’t give me a second look, because they’ll most likely imagine me swanning about in graveyards, flirting with some wasting illness. If I describe myself as a technical writer, and a client is looking for someone to write humorous ad copy, they may not be interested, because they’ll imagine me as someone who doesn’t focus on what’s funny and entertaining.

I struggled with this question of what to call myself when I first started considering freelance writing work. I’ve done many different kinds of writing in my life, from blogging to poetry, playwriting to short stories, and I’ve even got a novel rolling along slowly in the background. Professionally, I’ve written instructional content, but most people aren’t really sure what that means.

The name I chose

Ultimately, after hashing it out with an acquaintance of mine, I settled on the name “Technical Content Creator.” As far as I know, it’s a fairly novel name for what I do and want to do, and that may have its downsides. “Technical Content Creator” doesn’t conjure up a particular image, but, for me, I think that’s its strength. My hope is that it will function as a kind of speed bump. That when people encounter it, they’ll pause for a moment to consider what it means.

On the other hand, sometimes it’s easiest to just say, “I’m a technical writer” and leave it at that.