Healthcare and Tech Writing

The pen is not only mighter than the sword, it's also much more helpful.

This applies to a datasheet or user manual on medical device, website content for a hospital or medical center, patient information website, or a white paper of insurance policies.  Having clear and accurate information can be the difference between life and death in some situations. So this is an area where good technical writing skills become critical, because people's lives depend on it.

Regardless of how one views the Affordable Healthcare Act (Obamacare), it has opened the doors of healthcare to technical writers. According to the Bureau of Labor Statistics, the increasing complexity of medical and scientific information will continue to create more opportunities for technical writers.

Even from just personal observation, I noticed more healthcare-related gigs or jobs for technical and medical writers. Just do an internet search and you'll see. As a technical writer, you just not only have just plethora of opportunities, but you might be able to have a chance to play a part in improving healthcare.

One of the fundamental problems with healthcare as it's currently implemented is it doesn't seem address the issue of cost. 

According to a CBS article written earlier this year, healthcare costs will continue to rise in 2016. However, it may not be all doom and gloom. A recent PWC study shows virtual care, new health advisers, and the eventual "Cadillac tax" might lower costs. Whether any of these factors mentioned here increase or decrease costs remains to be seen.

But what are the factors of the increasing costs? Inefficiency and waste certainly play a role.

So what does this have to do with technical writers? Our organizational and writing prowess can at least help improve efficiency and reduce the amount of time wasted weeding through the vague and disorganized language in healthcare plans and information. If we are able to easily guide people through the healthcare world with easy-to-follow language and documentation, then we might be able to put practical steps in motion to reduce healthcare costs. There are two important things we need when it comes to healthcare documentation.

Importance of accurate content

Having accurate content is fundamental to good documentation, especially healthcare. This should be self-explanatory. But for those who don't have many scruples against inaccurate information, let me explain why this important. Inaccurate health information can cause harm to others and sometimes death. This will cause members to lose trust in the health care organization, which in turn could cause it to shut down, and you would be out of a job.

Now if you're working for an organization that doesn't care about accurate information, then get away from it as fast as you can. You don't want to be associated with something that it's incompetent in caring for its customers or doesn't care about them at all.

The member or the healthcare worker is responsible for finding accurate information. But, you should play a role by supplying accurate content. Ask the right questions and make sure each you understand what the SME is saying. Have them check the content you documented. People's live are at stake.

Importance of clear content

If the information is unclear, let's says a how to instruction on operating a medical device, then these unclear instructions might cause harm or death to the one using the device. This is not something you want on your conscience. Again, make you ask the right questions and understand what the SME is saying. Do a QA check on the documentation to make sure it's clearly communicating the message it's trying to convey. You'll be surprise how many changes you might need to make sure as you go step-by-step with the product or service you're documenting. Doing the check can go a long way and will save lives in the process.

Give purpose to your career

You need to have passion for people's health and well being. Otherwise, the quality of documentation in healthcare will suffer. If you want to give meaning to what you're doing as a technical writer, then writing in the healthcare field is a place to fulfill that meaning. People's lives depend on it.

Tech Writing Doesn't Equal Science Fiction

For the love of all things decent and true, in whatever you do, don't write fiction in a technical document. In other words, document only what exists.

Some might want you to create something that's called vaporware in documentation. Vaporware is touting a feature or features in a software, or even software, that doesn't yet exist. There's also a chance it may never exist.

If an SME or even management tells you to write or document that doesn't yet exist, please gently, but firmly tell them no. Just plainly tell them, "until we have an actual feature, product, or whatever that is actually in existence, let's leave this out of the technical documents, especially user manuals." I have run across a few SMEs who wanted to document steps or entire sections in user manuals that still in dreamland.

I am picking on rare cases where people will try to cajole you to write vaporware. Most SMEs have better sense than that. But if the rarities do try to pressure you to write science fiction, then you respond with some reasons why.

Credibility Gap

Losing credibility should be reason number one in avoiding vaporware to show up in your documentation.

If you put out some documentation that should be considered creative writing, the customer will lose faith in your product(s) and even lose faith in the company itself.

If a customer is trying to use a certain feature in a software and it's not there, imagine the frustration and confusion they might have. And then their frustration and confusion becomes skepticism of your company when they realize nothing that's written exists.

Not to mention, this is cheating the customer. They paid for a software or product. It's implied that all features are present. (Now whether it works properly is different story all together.) If there are features in a document, they had better be there.

If you're having a hard time understanding this, switch the roles around. Imagine you're the customer. And you bought furniture to put together. Then, you find out half of the parts listed in the manual were never made. Imagine how you will feel.

Customers will speak out

Before I was a technical writer, I worked in food service. I was told by the store manager, while training to be a manager myself, that if a customer has a bad experience, they will tell ten others, on average, about their experience.

Now this was before the Internet became available to the public and way before social media. Imagine how far news of bad customer experience can spread. Things go viral all the time. Let's hope a company you're working for doesn't go viral negatively because they were too lazy or dishonest to actually to create the features or even the product itself.

Now if a company has a total disregard to what I've said, then in my humble opinion, they shouldn't exist--like vaporware. Instead, they should evaporate like all other bad businesses do.

Easy to forget vaporware is there

You might hear a defense of documenting vaporware that's goes along these lines: just put this in anyway because we'll go back and create the features. With all the other things you have to keep track of during a product release, it's to easy to forget vaporware is in your document.

In my early days as a technical writer, I've had SMEs tell me to put vaporware in. So I put them in and guess what happened: the document went out with the product because we never got back to it before release time.

It wasn't until I put my foot down to document only what exists that the practice of documenting vaporware evaporated at a place I once worked at.

An exception to document the not yet

There might be exceptions to documents that don't exist like a proposal internally between departments, programmers, or engineers, so that they can get an idea of what to create. But for ALL external documents that are going out to customers, it should be big NO.

Serious considerations

If you work at a company where vaporware appears in your documents, I would everything possible to stamp it out and reject any spurious material that comes your way.

If your company's management or leadership is okay with vaporware, encourages it, or even demands it, then I would quit as soon as possible. If you're a contractor, then I would stop doing business with them as soon as possible.

If the company doesn't care about its reputation, then you should, at least, care about yours.

Now if you're okay with documenting vaporware, then my suggestion is to seriously consider writing science fiction. At least with that type of writing, you will have more credibility.

Project Management: The Next Logical Step

I don't know about you, but I've heard the job title known as "project manager" thrown around quite a bit. I also met a few project managers who were technical writers at one point.

What's interesting is that I've seen career maps for technical writers and one path is project management.

If you don't know what project management is, that's okay. I was in the same boat not too long ago as well. I'll try to explain what this job is the best I can.

My question is why do some technical writers become project managers? Is this a logical progression for those of us who've been in the documentation trenches for a while? I'm not sure. But I think I have a guess as to why this seems to happen.

Now before I give my hunch on why technical writers become project managers, let me explain what project management is.

According to Wikipedia, "project management is the discipline of initiating, planning, executing, controlling, and closing the work of a team to achieve specific goals and meet specific success criteria."

In others words, you're doing everything possible to make sure a project gets properly executed. You might manage different people, such as technical writers, to make they do their part with the project.

You might coordinate with various teams to make sure they work together to move the project along.

If there are trouble spots or impediments with the project, you might need to make some adjustments anywhere from shifting people around to coming up with a new plan on how to execute a project. As a project manager, you're there to see the project through.

Now what does project management have to do with technical writing?

Believe it or not, project management is built into technical writing. As a technical writer, a document is like a project. We are responsible for doing everything possible to make sure a document gets published and goes out the door with the product or service.

We come up with plans on how to complete a document. We also create an outline of what the document would look like.

Project managers have to create plans on how to complete a project. They need to have a bird's eye of the project.

Do you see a parallel here?

We have to work with different SMEs to get different pieces of content for a document, especially if it involves multiple chapters or a team of developers or engineers. You have to coordinate to make sure who does what and when. When you work with SMEs, mostly likely you'll be working with their manager to coordinate the deadlines.

Again, with a project manager, they need to coordinate with different people, teams, and managers to do their part of the project.

Collaboration and coordination are inherit in both technical writing and project management.

And finally, we technical writers have to juggle multiple documents to make sure they go out at the right time and are done well. Project managers have to juggle multiple projects to make sure they're executed correctly and on time.

I could go and go on about the similarities between the two, but I think you get the picture.

So what's my guess? It's understandable why technical writers become project managers. They want better recognition and pay for what they have been doing all this time.

Documentation and Gardening

Whenever I get a chance, I enjoy giving my green thumb a workout and caring for plants that bear fruit. Unfortunately, I'm not doing any gardening right now because of a drought and other factors. However, I'm still nursing an orchid plant. Where am I going with this?

I haven't suddenly shifted gears and turned this blog into a gardening one.  But I think gardening and documentation have something in common: they both take tenacity and patience.

Let me draw some parallels between the two.

Plan ahead. Before you plant a garden, you need to do some research. For example, what kind of soil are you going to use. Does the plant need more sunlight or more shade? How often do you need to water the plant?

With technical documentation, you need to do something similar. For example, you need to find out who the audience is that you're writing for. What kind of document are you writing? What kind of questions do you need to ask the SMEs? How will you structure the document?

Answering these questions will go a long way to help you to successfully complete a technical document and create a good garden. 

Be persistent and flexible. To make sure your garden thrives, you need to be active in caring for your plants. Constant care will help your garden grow. You also need to be willing to make some shifts when your garden isn't flourishing.

For example, you might need to change the location of your plants so they get more sunlight. If you have trees that have been bearing fruits for a while but the harvest declines each year, you need to prune them. There's also a possibility you need to completely uproot dead trees and plants because they're diseased or dying.

It's the same thing with documentation. Documentation isn't going to write itself. If you need to submit a technical document, you need to write it first. You may need to make adjustments to your document as it grows or evolves. For example, what you started off with may need to change because it's not reflecting the product, service, or the subject anymore. Or let's say you're documenting software and there are some new features for the upcoming release. You need to write the documentation to reflect these changes. There may even be documentation you need to trash but it's simply not applicable anymore

As a technical writer, expect you may need to do a writing and rewriting with documents you slaved away for hours, days, months, or even years. And the same thing with gardening, you may need to start over after a long time of caring for that one orchid. But if you are persistent and flexible, you should be able to overcome any obstacle that comes your way.

Factor in the unexpected. A disease might kill your plants. This actually happened to my zucchini plants one year. Or you might have seeds that are D.O.A. It's the same with documents. The "powers that be" might pull the plug on a project and the documents will die with it. Or the project goes in a completely different direction and the documentation needs to do the same. What if a company folds or someone you're working with suddenly quits? These are things that can happen and you need to account for these possibilities mentally when writing documentation. 

Be patient. Your garden isn't going to grow and yield fruit overnight. You shouldn't expect documentation to be completed overnight either. Sometimes, you'll be waiting for SMEs to get around to your questions when you want to finish up a section of the document. You might be waiting anywhere from hours to months to finish this up. Even if you try to follow up with the SME, he or she might not simply have the time. You need to move on with another document until they're ready.

If you are willing to deal with the dynamics of this universe, then you should be able to write technical documentation and plant a garden.

{

Why Placeholders

Today, we're going to talk about placeholders. According to the Wiktionary, a placeholder means:

noun (plural placeholders)
Something used or included temporarily or as a substitute for something that is not known or must remain generic; that which holds, denotes or reserves a place for something to come later.

If you haven't stopped reading, let me explain why I discussing something that seems insignificant.

While they seem unimportant, placeholders help capture the big picture of a document. They are especially helpful when you have a document with fields or you are crafting a template. Rather trying to reinvent the wheel, you can simply fill in or replace the content you want. But you will have the look and feel and structure of the document you're writing.

Placeholders are also a prelude to something better, meaningful, or complete. In my humble opinion, they are a significant step to help you paint, or in this case write, an instructional or informative picture.

Now, I want to get to the heart of what I'm saying. Placeholders aren't just some bits of text or pixels on a screen. They are stepping stones in life. 

Every job we have is a placeholder. It doesn't matter whether we work somewhere for 30 days or 30 years, it's temporary. Even if you plan to work there for the rest of life, there are some things you can't control:  a company folding, a company eliminating the tech pubs team, you becoming debilitated in some way so you can't work anymore, you taking care of a loved one long-term, or even you dying.

No job on this earth lasts forever.  Job security is a myth. Work is a placeholder until something else comes along. You might need to mentally prepare yourself for this possibility.

And for us independent contractors,our projects are just a placeholder until we fulfill the bigger picture. Let's say you're hired to do a project that just rebranding and minor updates on some company's documents for a couple of months. It may seem like droning busywork to us. But to the company, there's a bigger picture.

What if they are trying remake themselves to better serve their customers? What they are being merged with another company, and the documents have to represent this change? The documents in either scenario are a part of a bigger picture that the client is trying to show to their customers.

And finally, our work could be foreshadowing of something better or meaningful. Some of us technical writers may go on to be novelists. Having the discipline to finish a manual can also translate into a focus on writing and completing a novel.

Or maybe some will go on to be a role where we have to mediate between people who are in conflict. As a technical writer, you have to learn to how to build relationships with different groups of people to create a technical document. Technical writing is a very collaborative process. Whether that's interviewing an SME or guiding SME through their document on how to reshape it, you're working together.

A technical document is the result of building bridges with each other, so you can a build a bridge with the customer using the information you've written. I've seen tech writers move on to be project managers based on their experience in this aspect of technical writing.

Or maybe, some of us who are content with the possibility of staying as technical writers, like myself. Changing careers doesn't always mean it's a sign of something better. Just staying in the same role has its rewards. You can increase in your knowledge about subject you're writing about. Or perhaps, if you work on something from a different field, your knowledge base expands. 

I once told someone I was perfectly fine staying a technical writer. It doesn't mean I'm happy being stagnant. I'm just happy and grateful in what I do. And along the way, I've learned some things. I feel like I'm always learning when I work on a document.

So the next time you see a placeholder, ponder on what its role is and how it can apply to your life.

Technical Writing: Ubiquitous, Instrinic, Subtle

When we think of technical writing, we might come up with some different ideas. We might think of a neurotic wordsmith, straining over grammar, style, and finicky about formats when creating documentation. Or, maybe an engineer just waiting to unleash their inner writer, waiting to plaster their prose on the screen, and waiting to release to the world the greatest manual ever written. Most likely, though, they are someone who got stuck writing something because no one else wanted to do it.

And speaking of reading documentation, how about the things we toss to aside because they don't make any sense when we're trying to put something together. Yep, guilty as charged! The list can go on and on. I don't think you and I want to fall asleep while listing out these ideas. I'm getting drowsy thinking about it.

Whenever anyone asked me what I do and I say technical writer, sometimes I get a puzzled look. When I say I write instructions, they say okay and nod. Anyway, where the heck am I going with this.

If we are just viewing technical writing as something on a screen or on paper, we are limiting ourselves on what technical writing or, as I like to say, technical communication, is.

Technical writing is everywhere. Yes, the user guides, on-line helps, API documents, white papers, tutorials, quickstarts, how-tos, the hokey pokey and turn yourself around song, or whatever fancy, shiny titles you come up with. Other than helping to keep a writer employed, why is there so much technical writing out there?

In my humble opinion, I think it's because technical writing is intrinsic to us human beings. When we perform dance steps, fish, hunt, drive a car, using a programming language, cooking a meal, our inclination is to show others how to do this. This is one of the ways information and knowledge spreads. We have been showing others how to do something for ages.

Even things like teaching a Tae Kwon Do class, preaching a sermon, or parenting a child, are a form of technical communication. You're instructing others how to do something or you're explaining what something is. Technical writing is the written manifestation of the verbal instructions and physical demonstrations.

Finally, technical writing can be subtle. When we do our normal routines, we forget that there are steps involved and they fade into the background. We just do it. It could be anything from making coffee, tying your shoes, changing a diaper, or brushing your teeth. We don't think about it.

I remember one time I had to write step-by-step instructions on something I normally do. When I took up this exercise, I thought this was going to be easy. But when I had to write down the steps, I realized how many things I didn't think about while performing this routine task. It made me think about how much we take for granted when don't think about what we do. It's only when I began to write it down, that I paused to clear up my thoughts and to make sure I didn't miss anything.

So, the next time you look at a manual, a standard operation procedure guide, or an on-line tutorial, stop and think how much technical writing there is in our world, whether it's obvious or not.

Hello World!

My name is William McFadden and I have been a technical writer for over 18 years. What I'm hoping to accomplish here is to share my experiences, insights, and my philosophy of technical communication. And maybe, do some actual technical writing here. I don't want to get hung up on what tools to use or whether you should learn some programming language or not. Granted, these are helpful. I'm focused on talking about some core principles of technical writing, as well as issues that may surround it. I don't speak for all technical writers out there. I'm just one guy who's been doing this for a while. I'm hoping to encourage those who are new writers to consider this writing style or prose. I'm also hoping to encourage those who have been doing this for a while to continue. Thank you for stopping by. Hope you come again soon.