Putting Placeholders in your Life

There are times when you need to put a placeholder or two in your career. What I mean by that is when you're experiencing dry periods, it's time to take a job or two that may not be technical writing. Now I'm talking to those who are freelancers, independent contractors, or in between jobs. 

If you don't fall under these categories, that's okay. Feel free to follow along or just skip this post. If you do fall under these categories, it's a choice that you may need to make. It doesn't mean your career is over. It just means it's a stop-gap from going hungry.  Now here are some things that might help.

Don't be too proud

First off, don't be too proud to take any job. If months have gone by and you're not getting a bite, it's time you need to take a job to have food and shelter. If you think you're above it all, you won't get a job with that attitude. Be confident in your abilities but don't be arrogant. Attitude is a key factor in getting a job. 

Interviews may be determined on the tone of your voice and how you present yourself. Who wants to hire a pompous jerk? Sorry for being strong here. But seriously, who wants that except for other pompous jerks. However, I think pompous jerks can't even stand each other, so no luck there. 

If you think you're too good for a lowly service job, then you should stop reading and write me off as a hack. I can tell you this: arrogance doesn't help a writer grow. Having a humble and teachable heart does. 

But if you have a humble yet professional mindset, it will go a long way in landing a job.

 

Find a job that can use your abilities

If you need to find a job, then it would make life easier and more enjoyable if you find a job that uses some of your abilities. Brainstorm and come up with a list of jobs you would like to apply to. I'll give you a couple of examples.

Content writing is something you can easily take on since it's writing. If it wouldn't be hard leap to take, especially if you're writing technical content. The only problem with content writing, based on my experience, is that a lot of it is low pay, because there's a lot of content mills out there. 

I don't take a hard stand against content mills, because I write for them on occasion. A little money is better than no money. The issue I have with content mills is the amount of time you need to spend belting out an article or short for low pay. If you can find higher paying content writing gigs, go for it. If you do decide to go with content mills, than trying finding articles that won't take much effort or time to do. Remember your time and efforts are more important than money.

Another example is merchandising. Merchandising is similar to technical writing. They both are aiming to target a customer or an audience. They both have a process in organizing materials to create something orderly and easy-to-use. Merchandising uses an planogram to organize products or build a Point of Purchase (POP). Technical writing typically uses an outline to create documents. They both are detailed-orientated. They are both aim to foster relationships with the customers. They both use writing in some capacity. The big difference is that merchandising uses writing to create notes for internal use. Technical writing uses writing to create documents for external and internal use. 

The point is to search for a job were your skills are transferable. Not to mention, brainstorming of ideas helps you as a writer.

Don't take it personally, just be grateful

If you haven't gotten a technical writing gig in a while, don't take it personal. It's hard not to because it feels like nobody wants to hire you.  But there are other factors that we can't see like maybe companies are having budget problems or maybe they are unrealistically picky.

If you have a placeholder of a job, then don't think it's all you can get. This is just a season in your life. Just be grateful what you have. It's better than having nothing at all.

Work on honing your craft

Write. Write. Write. Writing anything during this time. This could anything from working on your cover letter or resume to starting a blog or a newsletter. Write a diary or a book if you want to.  In any case, your efforts aren't in vain. Your efforts are building up your craft, especially in the area of engaging your audience. The more you write, the more you hone your abilities as a writer.

New opportunities

Finally, take this dry period as a way to explore new opportunities. Maybe you can unlock your inner blogger or novelists during while you're working at the placeholder of a job. Or if you enjoy the placeholder job, then find writing positions in that field.

The point is to not see dry periods as just dry periods but opportunities to explore new avenues. 

Don't dare to compare

Whatever you do, don't compare to yourself to others as a technical writers. It doesn't matter whether you're trying to see if you're better or if you believe that you don't measure up to others, just don't do it. It will imprison you mentally and might affect your writing. Not to mention this is a waste of your time and energy.

There was a point in my career where I felt like a phony or a horrible technical writer because I don't have a BA. Due to some circumstances in my life, I couldn't go further in my higher education. So I settled for an AA, which I got after I became a technical writer.

When I saw other technical writers with a BA or MA, I felt very inadequate. This would get reinforced when I tried for other technical writing jobs but couldn't get them. It got worse when I saw other writers and focused on how they could write far better than me. And to top of it off, I would have some engineers who challenge me on grammar and style. I felt hopeless.

I would go to my office with my head down and would crouch in fear of engineers and others. My voice got shaky and uncertain. I was a mess for a while all because of these supposed points against me. Many times, I considered giving up not just technical writing, but writing all together.

Things were bleak until this Scripture verse came to my mind.

We do not dare to classify or compare ourselves with some who commend themselves. When they measure themselves by themselves and compare themselves with themselves, they are not wise. -- 2 Corinthians 10:12 NIV

As I kept thinking about this passage, I realized what I was by comparing to others was stupid and a waste of my time and energy. I realized I was my worst enemy. Other writers may write better than me. But so what? That's fine. Good for them. I'm not them and they are not me. And why was I assuming they are better? It could be their writing is just different. And that's good. It would be a very boring world if we all wrote the same way.

Writing is a thought process and we all think differently. The truth from this piece of Scripture started to break some light through the dark cloud over me. But the cloud was still there.

The next thing that made this dark cloud thin out was a book called Grammar Snobs Are Great Big Meanies by June Casagrande. This book was freeing for me. It showed that grammar and style are not always clear cut. Thanks June for writing such a much-needed book for us writers!

So whenever an engineer tried to challenge my editorial decisions, I wasn't threatened anymore. I would thank them for their feedback. I would change things if they were right or just simply better. If they were plain wrong or unnecessarily dogmatic, I would show them gently why I chose a certain way of saying things.

I may be a writer and know some principles of good grammar and style, but I don't know everything about it. I've even been wrong on things. Guess what? That's okay with me. As a writer, especially a technical writer, you have to be willing to learn and be humble about things.

The dark cloud was thin but still there. The last stronghold of my inferiority complex was my lack of a higher degree. It didn't lose its grip until others helped me see that my premise was faulty and nonsensical.

The dark cloud over me dissipated. I was free to pursue this simple adage: If you want to be a writer, then write.

A degree doesn't make a writer. It's what they write that makes them a writer. You can't trade experience for a piece of paper that says you're well-educated. In my humble opinion, real-world experience is more valuable than a degree.

Now for those of you who have BAs and MAs, God bless you. No one can take away the hard work and perseverance you put into getting that degree.

I have no regrets except one: the amount of days, weeks, months, and years I spent beating myself.

Technical Writer, a misnomer

Here goes my rant about technical writing:

What is a technical writer? A writer who writes about technical things? I guess. I don't know. It seems that what considered technical writing is a complete misnomer. Why do I say this? It seems based on the many years of experience I have, I do very little original writing. At very best, it seems I can get write in the holes to make up for missing content. Most of the time, it just seems I am spending designing documents, proofreading, editing or rewriting muddied content.

Maybe I'm being picky but when I think about technical writing, it should be about writing technical content from scratch. This should be done by research, or interviewing SME, or both. But the fact that most of time, I don't get to write original content most of the time really calls into question the moniker known as "technical writer."

And if you want to write original technical content, then you need to be a programmer or an engineer. If that's the case, then these SME should write, revise, edit, design, and publish their documents themselves. Other than proofreading, rewriting the content, if needed, and designing the document, what do they need us for?

I wonder half the time, if I'm an actually a writer or a technical typist with style (now, there's a job title). But at the end of the day, it doesn't matter. I get paid to do what I do, when I do it.

I'm not being a crybaby for not writing original content most of the time. I don't mind doing what I do. I actually enjoy it. I'm merely calling in question the label "technical writer."

Maybe other terms like "content auditor" or "technical rewriter" would be better terms. I would be fine with using terms that exists already like "document designer", "technical editor," or "documentation specialists". I think these are better terms to describe to what we do, but the term technical writer, I dunno.

Maybe you're experience is different than mine. If you have written original technical content, then great. I have written ghostwritten original tech content as well. But to most, it wouldn't be considered technical writing. I'm just saying, unless you're writing original technical content, I think it's time to rethink this job label: technical writer.

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.