Strange Creatures

People are truly strange creatures. They will disappoint you. They will turn on you. They will abandon you. They will unfriend you, using FB terms, even if you've done nothing to hurt them and have been there to support them.

However, there are those who will be there for you even when you don't expect it. The truest friends may be people you pass by each time and not give a second thought. Maybe they are different from you but will stand shoulder to shoulder with you when you need it. And those that are like you will leave you in the dust. Maybe the people you have dismissed already will actually be someone you can trust. Or, maybe some you thought you can trust ends up dismissing you.

You never know with people. People may surprise you whether for good or for bad.

And if you're married, the friendship you need to seek primarily is your spouse. He or she must be or become your best friend. Your spouse is your true confidant, your true partner, your friend who will be there all the other "friends" vanished into the ether. Friends will be there for a season. Your spouse will be for life. And, God will there be for eternity. 

Going back to others, people may drift apart because either one or both friends change. Or, maybe it has nothing to do with you but they have circumstances they are going through. Major life changes and shifts in direction greatly affect things. Or, it is simply the case that some people just don't click with each other. It is unfortunate but that's life. Who knows.

In any case, we need to be graceful and understand that people are just that, people. They are flawed and messy. And we are too.

Understanding this can help us understand why things we create are flawed and need refinement from time to time. This includes documentation. We can have a clear, well-written, and accurate document but it's not perfect. Guess what, it won't be.

The human experience is truly strange one indeed.

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.