Perpetual Problem with Woulda, Coulda, Shoulda

When we look at back at something, let's be honest we all do this, and say I coulda have done this, or I woulda done this instead, or I shoulda done that, there's a problem if we let these thoughts go unchecked. The problem is we'll be stuck in a perpetual loop of regret.

Let's suppose we could go back in time and do X instead of Y. If we did X, then we'll say the same thing that I shoulda, coulda, or woulda done Z instead. Let's say you do Z, then we'll say same about A and B and so on.  But it's not just an neverending chain of things of we could have done. What about the neverending chain of events that would have been affected from the things we didn't do because we choose the alternative path?

Let's say we were able to do Y instead of X. How would it affect the world surrounding X if we didn't do X or maybe it would have affect W? 

It's maddening to think about it. So it's maddening to be stuck in a perpetual loop of woulda, coulda, shoulda.

Don't get me wrong. Reflecting on the past is good because it can help us learn from our past mistakes, grow from it, and help us move forward successfully. But if we're not careful, we end up dwelling on the past and fall into trap of endless rumination and perseveration. 

This is true with life, careers, and even documentation.

When we create documentation, though there should be fundamental questions to ask before you start, there are different ways to approach it. Different circumstances require different approaches. In those moments, sometimes, we just don't come at it the best way. I know I haven't many times throughout my career as a technical writer. There are times where I overlook something or didn't document the features as clear as I should have, especially when my knowledge was limited on a subject, or I didn't ask the SME the right questions, or both.

But rather than beating myself up in a loop of woulda, coulda, shoulda, I try to reflect on it and move on. Yes, it's hard to not go back and think I could have done something better. But if I did, it wouldn't be the documentation that it is. And if I could go back, I would probably make the content worse in some ways because of whatever unforseen factors. 

The fundamental flaw with wishing to time travel is we assume we're going to make it better. How do know if we will improve the past? What if we make it worse if we didn't let history play out as it did? What lessons would we fail to learn?

I'm not much of a fan of time travelling stuff or even some alternate history because of this flawed thinking. But I do enjoy the JRPG "Chrono Trigger" and liked PKD's novel "The Man in the High Castle" and still have a couple of Harry Turtledove's novels to read. Beyond that, I have no interest. 

Of course, I'm assuming the worst but it's the flip side of assuming the best. In either case, they're unproven assumptions, so it's fruitless to dwell on woulda, coulda, or shoulda.  The movie "It's a Wonderful Life" shows the downside of this kind of thinking when taken to its extreme. Though it's become cliché, the message is still powerful there. Besides, clichés wouldn't exist if they weren't effective with our psyche. 

The past is there to learn from, even with documentation, so we can move forward into the future. To yearn that we wish we could somehow change the past is a waste of one of the most precious gifts that God has given us: life and time. It will eat away at your soul if you do, where you can't see what's in front of you.

Unlike real life, the beauty of documentation is it can be changed. We can improve it by learning from our past mistakes and continue to improve it in the future.

So rather than pining away about the past or fretting about a future we can't control, let's focus on living in the present. Let's take each day and document at a time. I'm not saying this from a high holy horse. I'm telling myself this as well. I struggle with living in the present but I want to. Let's heed what Jesus said about this. For if we do, we'll have peace and know how to move forward, regardless of our circumstances, even if they're crappy right now.

Matthew 6:25-34 KJV

[25] Therefore I say unto you, Take no thought for your life, what ye shall eat, or what ye shall drink; nor yet for your body, what ye shall put on. Is not the life more than meat, and the body than raiment? [26] Behold the fowls of the air: for they sow not, neither do they reap, nor gather into barns; yet your heavenly Father feedeth them. Are ye not much better than they? [27] Which of you by taking thought can add one cubit unto his stature? [28] And why take ye thought for raiment? Consider the lilies of the field, how they grow; they toil not, neither do they spin: [29] and yet I say unto you, That even Solomon in all his glory was not arrayed like one of these. [30] Wherefore, if God so clothe the grass of the field, which to day is, and to morrow is cast into the oven, shall he not much more clothe you, O ye of little faith? [31] Therefore take no thought, saying, What shall we eat? or, What shall we drink? or, Wherewithal shall we be clothed? [32] (For after all these things do the Gentiles seek:) for your heavenly Father knoweth that ye have need of all these things. [33] But seek ye first the kingdom of God, and his righteousness; and all these things shall be added unto you. [34] Take therefore no thought for the morrow: for the morrow shall take thought for the things of itself. Sufficient unto the day is the evil thereof.

Without growth and conflict, there's no story, even for technical writers

They say without conflict or growth in a character, there's no story. But why? Is this some tired trope or does it apply in real life? Well, let's walk this through. Is there a story when you're just going through your daily routine or when you're having choose between two great job offers? Is there a story when you're ready to get married but an old flame, whom you loved dearly, showed up? What makes even more interesting the reason for your breakup was a simple misunderstanding. Stories aren't just in the realm of fiction. Stories happen all the time in the real world! Why do some people read biographies, autobiographies, memoirs or historical accounts? They deem them to be worthy stories to read. 

Even the Bible, though I fully believe it's God's Word, has elements of story. Here are a few examples: 

• When God tested Abraham and told him to sacrifice his Isaac in Genesis 22. (Thankfully, there was a happy ending to this.)
• The story of Joseph and his brothers in Genesis 37-50.
• Joseph (different one) found out that Mary, who we was engaged to was pregnant and he wanted to divorce her quietly in Matthew 1:18-25. But he was informed that baby was the Promised Messiah, Jesus.
• When Jesus knew His death was near, He ask God, His Father, for Him not to go through it in Matthew 26:36-45, Mark 14:32-42, and Luke 22:39-46.

As conflict and growth of characters are essentials to crafting a good story, I believe these same elements are essential what makes us become better technical writers. How? Well, here are a few examples.

Let's say you're dealing with a difficult SME and you need to deliver some documentation by the next release, which is around the corner. This SME is hard to reach or gives little to no information on crucial parts for the information. So what do you do? Well, you either find a better way to reach this SME or find other key people who can help you get this information. To boot, you get this information at the last minute so you have little time to create quality documentation in the process right before release time.  Doesn't this sound more like a story than dealing with an easy SME, who gives you exactly what you need and when you need it to create the documentation and you're done way before it's time?

To be frank, I like it when there's no drama and I'm able to get everything I need to create a document without issues. I suppose I could say the story is everything lined up exactly as planned. But that's somewhat of a rarity in our line of work. Eventually, this stops becoming a story and morphs into a routine. Where's the growth or conflict? I don't like any conflicts either, but we live in a broken world, so unavoidable. But brokenness births countless stories. This is my problem with those who looking for a "utopia" or demand constant perfection. If we got what many wanted, stories will cease. 

Since conflict is inevitable, it's about knowing about how to find good resolutions to them. That's another key element in what makes a story. Who wants to read a story, unless you're an Eeyore, where there's no satisfying ending. Even open endings can be satisfying, if they're good. 

I'll share a time where there was conflict, resolution, and growth that came from it.

My Story: Creation of a Style Guide

When I was working at a company, the SMEs would fight me and the other technical writer on how to write the documentation. The SMEs wanted to write in passive voice instead of active voice. They also wanted to write "the user" when it was a clear case of writing "you", which was their audience. But to be fair to them, in my zeal for clarity and style, I would in some cases inadvertently change the meaning of the content. (This could have been avoided if we were given access to test the software but that's another topic.) 

We constantly battled over which words and phrases were correct, instead of focusing on releasing the documentation with the software. This fight drained the SMEs and us. The head of the company had to mediate in this conflict. After hearing both sides, he suggested that we technical writers create a style guide. So me and the other technical writer went to work to create the style guide. We used different sources, such as "The Elements of Style", to help us craft our tone and voice for the documentation. 

After much discussion and iterations, we were able to create a style guide that would help direct us and the SMEs on how the documentation would sound. It wasn't perfect, for no style guide is, but it reduced the fights to nearly zero. Those who wanted to fight still, we would just refer them to the style guide and the directive we got from the head of the company about this. 

We both became better technical writers from this. Though at that time, I hated going through every bit of this. I look back and thank God that this happened. If it didn't, I wouldn't have grown as a technical writer.  I learned to better balance clarity and style, while retaining the original meaning of the SMEs intended. By having this balance, the intended audience will get clear and accurate information. This is not to say I've perfected this, but I constantly strive for this balance whenever I create documentation. I've also learned to ask better fundamental questions to better get this balance. And when possible, I ask for ways for me to test what I am writing about. Before this conflict, that wasn't on my mind. 

I have to constantly remind myself conflicts can bring growth. It's too easy to wish a life without problems. Let's resist this silly (quite frankly, unbiblical) thinking. Without conflicts, there's no story. Without story, there's no life. Without life, there's no world.

Collaborate, Collaborate, Collaborate

Someone recently asked me if a technical writer is someone who collaborates with SMEs and takes technical jargon to make it into plain, easy-to-understand language. I responded with a resounding yes. They were happy with this response because others have told them otherwise. 

I don't understand why some are trying to change the definition of a technical writer. If I had to venture a guess, it might be they're trying to make a technical writer "a more valuable" role. But these changes tend to be (not always) counterinituitive, confusing, and overstepping. And, if you keep changing the definition, the role of technical writer ceases to be.

It's true we technical writers might do more than what this person asked me. I have. But at the heart of technical writing, besides writing concise, clear sentences, is collaboration, collaboration, collaboration.

Collaboration with the SMEs is the lifeblood of technical writing. Everything flows from this effort. Without it, you have no documentation. (Or at best, stilted, inaccurate, and myopic ones.) 

This type of writing is a joint effort. Unless you're creating the tool by yourself, you don't make up text out of the thin air. Technical writing is based something else greater than the writing itself. And someone almost always has created this something else. So your job as a technical writer is to collaborate with that someone, also known as a SME, to take that technical information of this something they created to make it clear, so your audience can easily understand it. 

As a technical writer, you not only have to continuously sharpen your writing skills but also master the art of collaboration. This skill many lack. When you can collaborate well with others, you've already added greater value to your role. How well anyone can collaborate can make or break documentation (or even an organization itself).

The challenge is taking other perspectives on the same information and present it in a unifying voice through documentation. But that's also the fun and rewarding part. 

Through collaboration, you end up creating something better you can imagine. We're only limited by our own thinking. So when we work with others, it expands our mind to where we can take the documentation. And when you publish a document, it should not just give us a sense of accomplishment but also help us stay grounded and humble, since it's a team effort.

You have to lay aside your ego as a technical writer. Otherwise, you have no business being a technical writer. If anyone is telling you otherwise, especially if they come from within our circles, we need to push back and say no. 

Benefits of technical writing

This post is aimed at either those who are thinking about becoming a technical writer or are new at it. But if you're also a seasoned vet, feel free to come along for the ride too.

The following shows how technical writing can help you become a stronger writer. This isn't an exhaustive list. These are just ones that came to mind. 

Improves your writing 

The first benefit of technical writing is that it can improve your writing. When you're constantly documenting, you're constantly writing. And when you're constantly writing, you're constantly getting better. 

Writing is like anything else. To get better, you need to practice, practice, practice.  It's also real world experience to improve your writing. You'll most likely get feedback on what you wrote, so it can help you know how to better document something.

Also, as a technical writer, you need to write succinctly.  Be clear. Be concise. Be straight to the point. Just explain how something works. To become a stronger writer, write in short, clear sentences. Preferably 20 words or less per sentence. Also, write in active voice. If you're explaining how perform a task, use active voice, so it's clear who's performing the action.

Your goal as a technical writer is to clearly communicate a point to your readers. This might seem overwhelming. But don't worry. The more you write, the easier it will get to communicate clearly. Writing will be always be hard work, but you'll know what to do as you gain more experience. 

Reduces or eliminates writer's block

The second benefit of technical writing is it can reduce or eliminate writer's block. What helps in is the fact you have something to write about in front of you. If you have access to a software or a tool, you don't have worry about formulating words out of thin air. You just have to explain how something works based on how it functions. You might also have to describe it, but you don't rely on your imagination. Now, if you don't have access to what you're writing about, make sure you get it.

Once you get an understanding how the tool or software, the words will just flow out. There were times, even I created an outline of a document and interviewed the SME, I didn't have much to say. But after I was able to test and play with the product I'm writing about, the writer's block dissipated.

This seems like an unfair advantage since I have something that's front of me to write about. But anything that gets you past writer's block counts. Let's not assume you must solely rely on your own mind to get pass the blocks. That's not only an unrealistic expectation, that's just false. Any honest writer will admit something outside of themselves helped them overcome writer's block. 

Technical writing just so has it built-in as a profession to overcome writer's block. This built-in remedy is seeking an understanding of what you're trying to write. And if you apply across the board, where you have a clear direction of what you're trying write, you should be overcome the blocks when they come.

Before I became a technical writer, I used to be paralyzed by writer's block constantly. Even when I was a journalist, I struggled to write an article. But now, I can write past the block. Many times, I write way more than I should and I have to prune back quite a bit before I publish. 

Now, we'll always encounter writer's block because we're human. But having a good understanding or direction what you want to write should help you move past it. This leads us to the next benefit.

Organizes your thoughts, even for your creative side

Technical writing can help you organize how you write information. 

When you're explaining how a product works, you'll explain it in a logical order. For example, if I had to explain how to use a wind-up toy car, I would say something like this:

1. Remove the car out from the package.

2. Place the car on a smooth surface.

3. While on the surface, hold the car and turn the wind-up key clockwise until it's fully wound.

4. Let go of the car. 

Explaining things in a logical order wouldn't just apply a set of instructions in a document. You'll be able to structure the doc in a logical order. And if there are a set of related docs, you'll be able to structure them in a way it makes sense.

This is not something you will be able to pick up overnight. The more you understand the product or service you're writing about, the easier it will become to organize content and documentation in a logical order. Being able to map out documentation is key to becoming a solid technical writer.

This benefit isn't confined to technical writing. You can use in other forms of writing, such as novel writing. If you can map out a novel, you can increase your chances in finishing it. (Pantsing a novel is good too. That's my favored approach with first drafts. But if you struggle with writer's block, then mapping might be better.) 

The difference between writing and great writing is not the words themselves, but how you arrange them. 

Better see big picture and details

This fourth benefit also doesn't come immediately; it just emerges. As you understand what you're writing about, you'll start forming a holistic approach to documentation. If there are a set of products or services, you'll start forming mental links between them and creating a documentation chain how they fit together. And as you deepen your understanding of these products and services, you can see how they can benefit your customers. And once you see this bigger picture, you'll have a better grasp on how to write the documentation. Then, the quality of the documentation improves.

As for the details, it too just emerges over times. At first, you might start off just catching grammatical or stylistic issues from either Subject Matter Experts (SMEs), fellow technical writers, if there are others, or yourself. But as you go, you might start noticing other details, such as wonkiness in the User Interface (UI), the pictures or code examples don't reflect what's in the text, or the product or service doesn't do what's supposed to. 

Once you get more in tuned with what you're writing about, your eye for details sharpens. You're not going to be perfect, because no human or even machine is. So, toss that unrealistic expectation into the trash. But, you'll pick up on stuff that's off-kilter. By having an eyes for details where you can tell those who create the product or service if you see something, you might make a difference in improving how your organization can serve their customers.

Focuses your writing 

I love this quote from Mark Twain about what makes a successful book:

"A successful book is not made of what is in it, but what is left out of it."

We can also apply this to technical writing, which leads us to the fifth benefit.  Technical writing can help you focus your writing.

Once you know you understand your audience, you can focus what information you want to include in your documentation. For example, if you there's a screen capture tool and it's for a typical user, you will only include step-by-step instructions on how to take a screenshot. You wouldn't any technical details or backend information about this tool. Now, let's say I had to write documentation about this same tool for backend developers, then I wouldn't include the step-by-step instructions on creating a screenshot. Instead, I would probably create an API documentation for this tool.

Great writing isn't just simply the words or how you organize them. It's also what you include and what left out. It's about focus. This is why knowing your audience matters.  

Always learning something new

This last benefit is built into technical writing. As you document a tool or service, you learn something new about it works. Even if there are no new products or services to document, you learn something new through upgrades, revisions, or updates of these existing products or services. When there's something new to learn, this can keep your writing fresh and further deepens what you know. As you deepen your understanding, your writing also deepen. 

I've never felt technical writing gets stale because you can become this ever-expanding knowledge base of information.

The learning never stops, you just choose to stop learning.

Highs and lows but still good

I can say more but I think you get the picture.

Technical writing has had its highs and lows with me, even times when I want to be done with it. But it's the style of writing that I enjoy. I get to write, help others by explaining something to them, and get paid well for doing this. Sounds like a good deal for me. 

I've become a stronger writer from technical writing. I still enjoy it, even after all these years. I continue to get stronger as I go along. Lord willing, I'll continue with technical writing. And I hope you either jump into the technical writing world or will continue with it too.

Pen and Paper?

Coffee with a Side of Pen and Paper -- Photo by Pixabay

When we take notes with devices, such as computers and smartphones, it's easy to overlook a set of invaluable tools: pen and paper. When you interview SMEs about high-tech features and concepts, you may to want these trusty old school tools in your arsenal.

So why am I advocating something low-tech?

Computers Fail

Computers crash. (Yes, even smartphones crash too.) That's just life. You're in the middle of taking notes and then bam. 

Unless you have autosave, or you're saving often, all your notes are gone. But autosave will only help you if you can get your machine up and running or if you can access your stuff on a cloud. Either way, this puts an unneeded stop in taking notes. You can avoid this by simply having a notepad and pen. 

When taking notes, I recommend having at least two pens, if possible, on hand in case one dies.

Faster or At least More Natural Note Taking

Unless you're a fast and skillful typist, you can disrupt a natural flow of a conversation or interview if you rely on a machine instead of notepads and pens to take notes. If you're taking notes on a machine and you're telling a SME to slow down or repeat themselves constantly, picture the interruptions. 

Also, the clicking and clacking of keys and the device itself can be distracting. Writing notes is quiet and keeps the conversation going.

Process the Information Better

Writing notes by hand increases the chances you'll understand the information better instead of typing them in a machine. And it increases the chances of you retaining the information after you written notes.

When I've taken notes by hand, I've always felt more connected and engaged with SMEs in what they're trying to say than when I've typed notes. Whenever I jot down technical concepts by hand so I can create a document, I like feel I can better understand and remember what they're saying. 

One of my favorite things to do as a technical writer is physically taking notes. I enjoy putting pen to paper when I interview a SME, walk through a product myself, or both. (I've also done this well in a remote environment.)

Unleashes Creativity

Handwriting notes seems to increase creativity, which is a boon for writers especially ones with a creative bent. 

According to Little Things, one of the benefits of writing things out by hand is it unleashes your creativity. On the surface, creativity and technical writing seem like oil and water. But not so. When you create a technical document, especially one from scratch and no template you need creative power. 

When I've taken notes by hand, I can get inklings on how to create the document and how to arrange the information in it. 

Is Typing Notes Useless?

If taking notes by hand is superior to taking notes by devices, then why do some people continue to use them instead of going back to pen and paper? 

There are a good few reasons to not to handwrite notes. 

One, if you have a disability. If you struggle with taking notes or unable to by hand, then by all means type, use a recorder, or any other method to record notes. Don't let anyone tell you otherwise. Use what works for you.

Two, supposedly you can write more notes by typing than by jotting them down. 

Three, you can share your notes a lot easier than trying to decipher someone's handwriting. And if you're going to share, it's easier to clean up your own typed notes easier. Why bother trying to fix up your chicken scratch when you can type it.

In cases where you need to share notes, I'll concede that typing is better. Here's what one writer says in defense of typing.

Though these writers seem to tilt towards handwriting, they highlight some possible advantages to typing notes too:

https://effectiviology.com/handwriting-vs-typing-how-to-take-notes/

https://www.clearvuehealth.com/writingtyping/

But their conclusion seems to be handwriting notes is the better way to go.

What About Recorders?

Using a recorder changes the dynamics of note taking. With a recorder, I'll also concede there's a definite advantage over pen and paper. But let's not forget one thing or should I say two: What happens if the device fails or if the battery dies. When that happens and you have no back up, then that's no good. 

If you're going to use a recorder, then I recommend having a notepad and pen and actively notes while you're interviewing a SME. That way, you have two ways of capturing the information. In this case, it's like two heads is better than one. And if you're doing that, you're still using pen and paper.

What About Digital Note Taking?

One plus about technology is it can eliminate some arguments or find a radical middle ground. This may be so with digital note taking.

Digital note taking seems like a good middle ground between clicking on keys or scribbling on a notepad. It seems it's the best of both worlds. So it's tempting for me to concede here too. But my response is this: What happens if the device fails when you take notes?

Commit to Keep and Bear Pen and Paper

Aside from seemingly, possible advantages of using devices, I remain committed to upholding the right to keep and bear pen and paper. For as long as I'm a technical writer, I'll use them when I interview SMEs.

I don't care what the sirens of technology and convenience say. I'm not turning them in. Neither should you. My pens and pads will stay with me. So listen here machines! You'll have to pry my pen and notepad out of my cold, dead hands. What about you?

Barriers to Entry

DISCLAIMER: This post is not authoritative. These barriers are merely one that I have encountered. These barriers (or perceived barriers) are based on my own interactions and the solely the opinions (possibly the mad opinions) of this writer. 

Photo by Travis Saylor

There seems to be a lot of technical writing jobs out there. But, it seems many technical writers, such as myself, are spending more time trying to get the next contract or job more than we have work itself. Many times, it seems we're either very busy documenting away or in between projects looking for work. Sometimes, it's for a very long time.

It would seem technical writers, such as myself, would get a job or a contract right away with the plethora of supposed opportunities out there. But, this doesn't seem to be the case. 

I've seen the same jobs or contracts posted for months. I've also ran into other technical writers who have been out of work for extended periods of time. Based on my interactions, it's not because they're bad at the what they do. There seems to be other factors. It seems to be there are barriers to entry for us technical writers to get a job or a contract.

Despite a few articles on the Internet that say technical writing is dying, that doesn't seem to be case. If any organization based their decisions to let technical writers go because of this, then they're sorely mistaken and misinformed. Actually, it would seem to be the opposite.

According to the The Bureau of Labor Statistics (BLS), technical writing is growing. According to their projections, technical writing is growing faster than some other occupations.  Also, according to the US News and World Report, technical writing is one of the best jobs for 2019. But it's quite possible these projections are flawed.

But the fact there are abundance of jobs, especially in tech, seem to show us technical writing is far from dead. Also, the fact there's a constant deluge of products, services, and innovations flooding society, so the possibilities to documenting them seems endless.  So, what's going on? What are the possible barriers?

Ever Growing List of Requirements

One barrier would be an ever growing list of requirements to get a technical writing job. Some of these newer jobs seems to be either something for programmers or the scientist. This would be acceptable except the technical writer is just a writer at the end of the day. Though, I believe writing what you know is very important, when did the technical writer become the sole realm of the academic elite. I would like to know when that was.

If technical writing is really belongs to these elites, then I guess I have been blessed whenever I got jobs. If one from such a priest class wants to explain me that I must have X,Y, Z piece of paper or I must an engineer or a scientist or whatever role of you approved of, then I will gracefully bow of out technical writing. But don't expect me to give up on writing all together.

Misunderstanding the Role

There seems to be a misunderstanding what technical writing is. It's not a scientist or a programmer who write. It's a highly trained writer, regardless of education or background, who break down complex highly technical information into easy-to-read prose. Unfortunately, many technical documents are so murky that nobody understands them. And throwing scientists or programmers into the task of documenting them muddies this even further.

Why do I say this? It's because SMEs might overlook some critical information when creating step-by-step information.  They assume their audience will know what they mean or imply. You can't do that with technical writing. You need to spell out each step. You may not need to define the terms because of the audience you're writing for should know, unless it's something new.

When you're showing someone how to do something, you need explain this clearly and one step a time. SMEs can miss needed steps and so can the technical writer. To see how daunting a task it is to document something step-by-step, check a previous post called Count All the Steps.

As a technical writer, you need to be the independent pair of eyes to break this information down, so you can catch the blind spots the SMEs overlooked. In my experience, though interviewing SMEs help give me information on creating a document, there are still gaps in it before it's complete. What the SME gives you is a starting point. You need to go through the software or the product yourself to document how to use it before you say the document is done.

Also, there are many different name for technical writer. Sometimes, they are called documentation specialists or even document engineers. It also doesn't help it seems organizations are using Instructional Designers to do a technical writer's job.

No disrespect to the Instructional Designers out there, but they are not technical writers. While the two occupations overlap quite a bit, they pursue two different goals.  I have had some who asked me if I have done instructional design and I had to say no. I'm a technical writer, not an instructional designer. So, this adds to the confusion.

Too Niche Orientated

It seems technical writing jobs are getting very niche orientated. But how can you get into them unless you get the experience? Even if you have the degree of that niche, there's no guarantee you're going to get that job.

Let's talk about tools. It's a tall order for companies to expect technical writer to know every tool out there. It's impossible. And if a company wants to shut good writers out because they don't know some arbitrary tool that not everyone uses, then they will be looking for a long time. (I guess that's the point with some of these folks.)

I feel the SMEs are dictating the terms of what they want as a technical writer and want a carbon copy of themself rather than looking for a good writer. You kind of have to wonder why many instructions and technical documents are horrible.

Any good technical writer will pick up any tool, programming language, or subject that comes their way. It's intrinsic for technical writers to adapt to any situation. If any technical writer tells you otherwise, then they need to get out of the field. Give us a chance!

All About Keywords

As for resumes, what many organizations or recruiters is look for certain keywords. Some say they don't seem to looking at cover letters either way. However, some say they do. Who's telling the truth? I have no idea.

In any case, many just use Applicant Tracking Software (ATS) to scan for keywords. So, they don't bother to look at the resume. The simple fact of relying software for certain keywords rather looking at someone's experience is another barrier.

They are reducing us to keywords rather than treating us as people. You even have articles that encourage you to use keywords in your resume so you can picked up by software. While using the right keywords will help your resume stand out, keywords aren't everything. We should be looking at the person's experience. A resume is a story of that person's experience. To simply look for keywords is degrading people and their story. This is wrong! But the moment we refuse to be reduced to mere keywords, the moment this barrier will come down.

Enough with NDA Fears

There's a bigger barrier and that's the problem of Non Disclosure Agreements (NDAs). While I understand why an organization would want us to sign an NDA, it's also not helpful for us because we, technical writers, would like to use samples of our work when you kick us to the curb at a moment's notice. (That's for another blog to expound why organizations are cold like this.)

We would like to show our work when other organizations are asking to provide samples. One time, I was speaking with the recruiter for a prospective contract and he was asking me for a sample, I told him I couldn't provide a sample because of NDAs. He told me the technical writers he interviewed said the same thing. 

While an NDA may not prohibit from sharing a sample, we also don't want to take the chance of getting sued by a company. Though the company may not have a leg to stand on from barring us from sharing a sample, an NDA is uncertain territory on whether we should have samples. I don't want to take the chance of finding out. My peers have seemed to have also taken the same overcautious road.

Unless you're writing internal or confidential information in an document, there's no reason for us to be barred from sharing a sample.

If you have a user guide going to your customers, then we should be able to share this since this is external communication. Perhaps, when technical writers have to sign NDAs, then there should be some exceptions for those who are in communications positions (such as copywriters or technical writers) in an organizations that we can share samples when our employment or contract ends. As for internal (not confidential) communication, we should be able to share this document with important information redacted from it. 

And from the organization's standpoint, I understand why they would want samples. They want to see how we do our work and if it's quality to them. I get it. A resume isn't enough. How can they trust we can do the job if they can't see it. 

Journalists, writers, photographers, and freelance copywriters have portfolios to show their work, why can't we. (There might be some technical writers who do have portfolios. And if you're one, then what I said doesn't apply. If you haven't gotten harassed for a portfolio, then I guess most of us are probably operating under unfounded fear and hurting ourselves in the process.)

Rethinking the Entire System

While this last point may not be a barrier per se, it might be causing problems. The whole idea of contracts and in-house technical writing might be adding to the barriers. 

These companies get to dictate the terms, make us fit their mold, and when there are done with us, they are discard us like we're trash. As far as independent contract gigs go, let's just be honest. It's really a nice way of calling us temp workers or you're a worker where the labor protections don't apply.

These companies are trying to make us feel like we're independent but we are really exploited by them. It's a devilish illusion!

It also doesn't help we have to compete with cheap labor from content farms or the like. Makes me so angry that they writers pennies for a lot of work. (But that's another post for another time.)

So what do we do? Let me offer some suggestions. Perhaps, technical writers should be in the realm of self-employed artisans. We should also somehow band together to form cooperatives or guilds so we can have the power to break down these barriers. Some might point out The Society of Technical Communication but it's just an association. It's not a force with teeth. 

If we band together in an organized fashion, like many workers have had to in the past, then we get to tell these organizations what it means to be a technical writer. It's not because we are the end be all. It's because we are ones doing the writing.

Though we need to serve our audience by creating the documentation that meets their needs, we also need to set up clear boundaries what's required to be a good technical writer. And what's required to be a good technical writer is this:

• Excellent written and oral communication skills.
• A willingness to learn new things, 
• A servant's heart.

I don't know. Maybe it's time for us technical writers to rise up peacefully yet boldly to smash all these barriers to entry.

If someone is reading this, I hope you can get this conversation going. If you can better identify different barriers or better articulate them, more power to you. I'm trying to do my part to save technical writing.

Writing is a craft, including technical writing, and we should guard it as such.

Always Expand Your Knowledge Base

When you're a technical writer, you're an ever expanding knowledge base. You're always learning, or you should keep learning, when you're crafting your prose explaining such and such product or service.

The beauty of being an ever expanding knowledge base is you don't need an advanced degree. But, you need the following:

• A teachable attitude
• Good communication skills
• Be an avid reader

Become an Avid Reader

Read all kinds of things, not just things pertaining to the job. Try reading anything from fantasy, science fiction, and mystery to non-fiction, news and opinion, and inspirational. I'm an avid reader. I read daily. I read more than I write. I write almost daily.

I enjoy expanding my knowledge and imagination and refining or even challenging my thinking or skills. If there's something that catches my eye, I look it up and read about it. Reading helps me become a better writer. I learn from others how to craft sentences. There are times when I will stop writing for a while just to read.

Even if you're well versed with a product line, a programming language, or industry, there's always something new to learn within them. So, try reading about what's going on in the industry and where it's heading. For if there was all there was in an industry, then I suspect there would be nothing further to document. And if there's nothing new to document, then it would be the end of technical writing.

I find being an avid reader really helps me recall or connect data points in my head when a pertinent conversation or situation arises.

(Though I don't actively read about technology or programming languages unless it's for a job, reading such works can be helpful because you become aware of possible things to write about.)

Hone Your Communication Skills

To be an ever expanding knowledge base, you need to hone in on good communication skills. These skills will actually help you grow as a technical writer. If you talk with an Subject Matter Expert (SME), you can learn a lot. You have to learn good deal about the thing you are documenting before you can document it. If you need to document similar products and services and uses the same terminology, you can just move forward with writing about them because you already talk to the SME. (Of course, you should still keep in contact with SMEs to make sure your knowledge is up-to-date.)

When I've interviewed SMEs, I get educated. I get both the big picture about the subject at hand and the details about it.

Taking notes down also reinforces what I learned from an interview. (When possible, I recommend taking notes by hand than by computer or device. Some have suggested writing notes by hand is far better than doing this digitally.)

Asking the right questions, taking good notes, and a listening ear will develop your technical writing skills. So how you can hone in your communication skills? The first and crucial step is learn how to listen. Practice active listening.

Have A Teachable Attitude

Finally, you must have a teachable attitude. You can't learn something if you're not willing to learn, even it runs counters to what you know and believe. You need to humble and realize you don't have all the answers. You also have to be willing to be okay with the possibility the answers you have already might be wrong. A teachable attitude will help you adapt to new situation. This will keep your technical writing alive and active.

A teachable attitude is the key to become an ever expanding knowledge base.

Adhere to a New Adage 

While technical writer doesn't contradict the famous adage:

"Write what you know".  

we need another adage that aptly captures this strange form of writing. It should be something like:

"Before you know what to write, go find out what it is first."

Keep Your Technical Writing Alive

By being an ever expanding knowledge base, it keeps your technical writing fresh and dynamic. For me, there's rarely a dull moment in creating documents. The very nature of technical writing is open-ended and expanding. This makes it a great career path because you can grow with it.

In my earlier days of technical writing, I came up with a mantra and it's one I still use to guide my craft. It's this:

The learning never stops; you just choose to stop learning.

 When you stop learning, your technical writing will start dying.

    

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.

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.