Without a shadow of a doubt

If you put out technical documentation you're unsure of, then there's a big problem. Chances are if you're not certain of some content in a document, then your audience may be uncertain too.

Unless you're dealing with theories or scientific findings in white papers, technical documentation must be a rock of certainty to the user. Why? It's because you're guiding your audience to do something. If you're not instructing them, then you're guiding them along to explain some information. In either case, you shouldn't fly blind on what you're writing or editing before you publish.

So how can you make sure you understand what you're writing?

Big picture

Understanding the big picture of a product or service of what you're about to document is extremely important. If you don't have an idea of what you're writing about, it will show. 

If you sit down with an SME, have them tell you briefly what something is. Once you get a gist of what you're writing, the rest is just taking the next steps. Don't get hung up on details. Those will follow as you move along. It's more important to take a step back to see the bigger picture, so you know how to create a document. 

Understand your audience

It's important to understand so you would know who are you are writing for. What kind of information will you include? What information not include? For example, if you're writing for a software company that helps electrical engineers create schematics of an electric circuit, you should find out what schematics and electrical circuits are before you proceed. However, you wouldn't explain what these things are to an electric engineer since they should know. You simply explain to them how to use the software. 

For more about knowing your audience, please check out what I said previously.

Ask Questions

If you're unclear on what you do, please ask questions. Ask and never assume. No one should expect a technical writer to be an SME. Do as much as research you can on your end. Then, ask the SME questions about the product or service you're uncertain about. Any SME worth their salt will be able to answer your questions. Don't be afraid to ask. It's better to ask plenty of questions and put out an accurate and clear document, than to put out a document that's unclear, inaccurate, and full of uncertainties.

Audience Matters

In the Lion King, Musafa's ghost told his son Simba to remember who he was. There's something that we tech writers, or we writers in general, can take that from that.  We need to remember who we are and why we are doing what we are doing.

Whether we want to admit it or not, as writers, we are doing what we do for the audience. Even if we are writing in our dairies (and yes, there are people who still write dairies, even blogs are diaries in of themselves, except they are in cyberspace), you are still writing for an audience.

Whether you are writing for one or one million, the end goal of writing is to communicate a message to the audience. With that in mind, we must tailor that message to them.

Understand Your Audience

This is key in writing a document. I can't stress how important it is to know your audience. This should be the first step before you type a character on the screen.

So why is this important? The obvious answer is for every document there is an audience. Why write anything to anyone if you don't understand who they are?

For example, you're not going to write a whitepaper for an electrical engineer audience to educate them on circuits, currents, transistors, or diodes. Since they know about electronics, you wouldn't waste your time--or theirs--defining these components. You should focus your attention on how to have electrical currents run through circuits better and with less power. Or maybe, you would show them how to create certain schematics for a chip.

Another example would be if you're creating a user guide on how to run an air conditioner written to the general audience, you're not going explain the nuts, bolts, materials, and components that were used to create the air conditioner. You're just going explain how to use it. You may also have surface technical specifications in the guide, like the amount of BTUs the air conditioner uses, but nothing beyond that. 

So before you write a document, know who you're writing for. Otherwise, the information in the document is worthless.

If you don't know who the audience is, then ask an SME or do some research yourself. Any SME worth their salt should be able to help you with this.

In any case, it's important to gauge your audience, so you know how much or how little information you need to communicate, as well as the type of information.

Listen to Your Audience

The second part of understanding your audience is to listen to them. If your audience is confused by certain portions of the document, there are missing steps, or the information is not as accurate as it should be, you need to take the feedback and improve it. In some ways, documentation is like software; it's fluid and it has bugs. Documentation gets better, like software (or at least should), if you listen to the complaints as well as the complements. Otherwise, the documentation is useless to the audience and they will find someone else who can meet their needs. So listen up!
 

Build a relationship with Your Audience

The third part of understanding your audience is to build a relationship with them. This is very similar to listening to your audience, except it's taking it to the next step. If you can, try to keep an open dialogue with them. See what works for them, what doesn't, and why. Have your audience complete surveys or even participate in usability tests on your documents. This can be useful to see if they can try find trouble spots as they're going through the document.


If you're able to do this, your audience will put more trust in your abilities. And you will be able to provide the audience the documentation they need. As a result, it's an ongoing, constantly-evolving relationship. It's a win-win situation.


Servant's role

Remember, documentation isn't about you. It's about them.  A technical writer is really a servant's role. If you prefer to being in charge, then pursue project management instead. If you choose that path, then I wish you well on that journey. But writing, especially technical writing, revolves around how to best serve the audience you're writing for.

Demystify the API

What is an API? A string of random letters floating in an alphabet soup?

API is more than an obscure acronym in the ocean of technical terms. It's actually becoming very relevant in some quadrants of technical writing.

API stands for Application Programming Interface. It means basically means a set of steps, routines, and procedures to create software or applications. 

Where technical writing comes into the play with APIs is that documenting how to use the programming language to create or modify a software or an application. You may have heard the terms "API Guide" or "API Manual." If not, that's okay. I've only heard the term a couple of years ago. 

From what I gather, these types of documentation are basically user manuals for software or app developers so they can create their programs. 

There are also some terms we should know when it comes to API documentation.  I don't want to say that these cover all there is to API, but you may run into these terms when you're either looking for your next gig or when your company decides to create API documentation. They are REST, SOAP, and Endpoints.

REST (REpresentational State Transfer) API
   
REST API doesn't mean procedures on how to create an application to help you sleep (though, I'm sure something like that out there exists).

REST API (or REST-ful API) means it's an API that based on the nuts and bolts and the structure (software architecture) of the Internet. This is not based on some markup language, like HTML or JavaScript, or some standard. It more of a style of an API. I'm not even sure if this is completely accurate to say. There's a reason why: REST-ful APIs depend on the organization that creates them.

Some REST-ful API can be done in JSON (JavaScript Object Notation), XML, or even HTTP. Again, it's a style or architecture an API is presented in. (API writers feel free to give some comments)

Now another type of API that's easier to pin down is SOAP API.

SOAP (Simple Object Access Protocol) API

SOAP API is more clean cut to define than REST API. No, it's not a way to create applications to produce bars of soap (again, there might an app out there to do that).

SOAP APIs are set of steps to create applications based on an XML Infoset. I guess it's good to know XML other than working with it in a structured authoring environment.

Endpoints

Another thing to note about API documentation is something called Endpoints. I have only heard of this term in the past a couple of months when I did an API document for a healthcare company.

An API endpoint is basically a procedure or a method of how an API will run.

You would typically see this with an example of code in the document. Then before or after the example, you would have the name of the method, say a command or a parameter, and the definition of it.

API endpoints depend on the organization that determines them.

Final Thoughts

It seems, at this point, the line between software developer and technical writer are blurred. Based on what I have seen, it seems that companies who are looking for API technical writers are basically looking for developers that can write. Many times that they looking for candidates who have experience with programming languages.

My question to them is, why look for technical writers if you can just use programmers to do the documentation? The only thing I can think of is that API documentation is fairly recent and somewhat uncharted for us technical writers. Whether API docs will be something for technical writers to do, or will finally just reside in the realm of software developers remains to be seen.

In any case, if you want to try your hand at API documentation, don't be disheartened. You can pick up programming languages either by being self-taught or taking courses.

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.

{