Monday, July 1, 2019

Why I Don't Talk Much About Tools and Tech

If you've read The Placeholder for some time, you may have notice I don't much talk about specific tools or technologies. This seems pretty strange for a technical writing blog. But there's a good reason why I shy away from such details. It's because these are just details that shift like the wind. I am more interested in the bigger picture of technical writing. 

There are some other technical writing blogs that may talk about these specific things. And if you're looking for these specifics, then go to them. But I intentionally created The Placeholder with a different angle.  

I created The Placeholder because I felt the principles of technical writing were getting lost in the seas of ever-shifting currents of tools and technology and in the mire of the aspiring technologist. When I saw the ever-growing requirements for technical writing jobs to know such and such tool and you must know such and such programming language rather looking at years of writing experience, I felt technical writing was morphing into something it's not. I created The Placeholder to be a small (probably quixotic) bulwark against this ever-growing tsunami of technological requirements and other obscure oddities for a writing job.

A technical writer is a writer, first and foremost, who documents about how certain technologies, products, or services work. A technical writer is not a technologist who merely writes. That may offend some for me to say this. But when you strip a technical writer of their odd exterior, that person is a writer underneath.

I have no interest in writing about things with a short shelf life. I am interested in writing about things that will last. Principles, if they are good, will last. But virtual tools and technologies change with the direction of the wind. For example, when I first started as a technical writer I used Pagemaker. Then, the hot tool to use was FrameMaker. FrameMaker was a great tool to use for creating big technical documents. I used to create technical documents with a lot of equations that were thousands of page long. I was even FrameMaker's defender when the powers that be at a company I used to work for suggested shifting over to Word. I told them no because Word, at that time, didn't have the capability to handle the technical documents we were doing. FrameMaker was the go-to tool for a technical writer. If you were doing help-authoring, at that time, you would use Robohelp

Now fast forward, FrameMaker has lost its preeminence. Also, where's Robohelp these days? Many are requiring InDesign to create technical documents or use Wordpress for bloggish-type technical writing or maybe for help documents. By the time you get a handle on a platform or tool, it shifts to something else. It's almost hopeless to stay completely current with this. But tools are tools. They are not essential to technical writing itself. What's essential is quality writing. 

Principles of good technical writing stay about the same. Principles like active voice, concise language, and presenting information where it's easy to follow stays the same. And these are the principles technical writing should be built upon, not upon tools or technology. They have been here before I became a technical writing. They will last when I am gone. But I also recognize technical writing principles don't stay frozen in time and that's fine, they shouldn't. These principles should evolve when needs arise. For example, more recent concerns like greater accessibility to documents for those with impairments. We should incorporate accessibility into the "technical writing rubric" because we need to make documents that are accessible to as many people possible. These are the things I care to write about.

Technology is a double-edged sword. So, I am not so interested in singing praises about any particular tool or technology. There are two only reasons why I enjoy technical writing. One, I get to write. Two, I get to help others. If the technologists want to take over the technical writing world and push folks like myself, then I will take my two passions elsewhere. If God makes it clear for me to leave technical writing, then I will graciously bow out. Otherwise, I will stay in it. And while I'm here, I do what I can to create quality documents.

As for programming or markup languages, I don't mind talking about them. Like the written language, they evolve but the principles stay the same. Like the written language is behind good pieces of literature, the programming languages are behind some helpful pieces of technology and software. In recent years, I have taken a liking to Markdown. I am happy to see some technical writing jobs out there now asking for those who know Markdown. I like Markdown because it helps focus on creating good writing, not get lost in the trappings of tools.

So if I am not writing about the latest such and such the STC is talking about, it's because these things fluctuate. They can do that and that's fine. But, I will do my own little thing here. Remember, tools change but principles of good technical writing stay the same.

Focus on your craft and learn how to best the serve the audience you're writing for and the rest will follow.

Friday, June 21, 2019

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.

Friday, May 24, 2019

Am I a Tech Writer or a Writer of Tech

Photo by Pixabay
Are you a tech writer or a writer of tech?  Depending how you answer this question, makes a difference. This sounds like I'm making a Shibboleth out of it. But this goes beyond semantics. Let me explain what it means to be a tech writer versus a writer of tech.


Technical Writer


A technical writer is one who writes and edits technical or business communication for a company or an organization. This could be anything from help files, reference guides, user guides, standard operation procedures (SOP), reference guides, or white papers. You're usually writing about a particular product, a service, or a procedure. Typically, you're showing people how to use a product or a service or how to perform a procedure. (When you write white papers, it's typically information about an idea, concept, or topic. And when you write reference guides, it's typically some referential material that usually compliments a product, a service, or a procedure.)

Technical writers typically wordsmith for a company as an employee or an independent contractor. The technical writer's goal is to show the customer how to do something. 

Technology Writer


A technology writer is one who writes about technology or upcoming technological trends. Technology writers typically write for periodicals, such as newspapers or magazines. Technology writers may even write for websites or blogs. Technology writers will write articles about a particular technology, trends, or a new product, such as a device, an accessory, or a laptop.

Technology writers typically work for the publication or the website or freelance for them, not the company it's writing about. Technology writers may even write how-to or troubleshooting articles.

The technology writer's goal is to inform the reader about technology.

Typically, Usually with Exceptions


You might have noticed I've used the modifiers "typically" or "usually". It's because there are exceptions to this. Sometimes, there's a blending between the two roles or where the writers work at. Also, what these writers write about may not always neatly into a category.


Tech Writer: A Catch-All, An Abbreviated Job Title, or A Cause of Confusion


Both types of writers are called tech writers. While this term is a nice catch-all, it gets dicey and probably has caused confusion with some. I've run into this myself, where people mistaken me for a technology writer. I've had to clarify I'm not a technology writer but a technical writer and what that means. I even misapplied for jobs where I thought they were calling for a technical writer, but they were really calling for a technology writer. 

Calling a technical writer or a technology writer a tech writer isn't wrong. Both start with "tech". Both write about technology. It's just technical writers and technology writers are approaching how to write about technology from different angles. 

I've been called a tech writer more than a technical writer in my time. I take no offense to this. I'm not suggesting either or both sides should stop using the term "tech writer." It's fine. As long as we define our terms in the context we are in, then we're good.

Sorry, if this is making your head spin. It's making mine. (Sometimes, I wish we could just write without the complications and call it a day.)

One Goal Out of Many Tech Writers


Despite our differences as tech writers, we should unite behind one underlying goal. This goal must be to help our audience by giving them accurate, helpful, appropriate, straightforward, and easy-to-follow information. As tech writers, we must adopt this common goal for our audience as our E pluribus unum.




Tuesday, May 7, 2019

Musings (or Ramblings) about the Command Line Interface

Whenever I type a command into a command line interface (CLI), I get this strange feeling I cannot really explain.

There's something about a command line interface that's seems so simple yet powerful. CLI is primeval yet advanced. It's raw yet full of flavor.

There's something about a CLI that makes wish we can just strip all the bells or whistles of an OS and just type away in this thing to start our applications (like many moons ago) or technologies.

When I type a command into a prompt, I get a sense of no distractions in doing something.  I'm focused. When I have to document on how to do something by writing a sentence or a paragraph about such and such followed by showing a command, I get a sense of fulfillment as a technical writer.

I feel like I am doing bare-bones technical writing to help transport the readers to whole new worlds. I enjoy this contrast of simple yet powerful from a CLI. One of my favorite things to write goes something like this:

"To do (fill in the blank), type:"

I wish I could just tell others how to perform certain actions by telling them to type a command. Once they're done, I can just write a brief description of the result.

I wish I could just write a document without using taking screenshots, using special tools, or even worrying about fonts. I wish I could just write the words themselves and let the reader see what happens for themself.

I wish I could take this a step further. I wish I could simply write a document using a typewriter. I like the act of typing commands and words without distractions, including a computer. It's a feeling I cannot fully explain.

My guess for this strange feeling is when you type a command, you get an action. Whether it's big or small, you can see the response. Commands are much like words. Words can paint a picture, whether it's grand or minuscule. When the reader read words, the reader responds by picturing an image in their mind. So when a craft a document about commands, you get a simple, yet lovely marriage between the two.

The CLI reminds me of the pattern in Genesis 1.  When God spoke a command, creation responded. As God spoke commands, He took a dark, watery, empty mess morphed it into this beautiful, blue planet full of life we see today. Though we have trashed this planet, Earth's beauty is still there. I just hope someday we can restore what has been trashed and become far better stewards of what God created. As for the CLI, I hope we can use it to help us restore the privacy and control that tech has taken from us.

Friday, April 19, 2019

My First Encounter with AI Recruiter

Had my first encounter with an AI Recruiter recently for a possible technical writing job. That was a very interesting experience knowing I was encountering a creature constructed from algorithms rather than a fellow human being.

On the surface, it wasn't unusual dialoguing with an AI recruiter. (I guess that's the point.) It felt like I was dealing with someone in a chat pod. I wrote briefly about my technical writing experience and what I did in difficult situations. She (her name was Wendy) asked me some more details.

So, we chatted back and forth. Once we're done with the conversation, Wendy told me to have a good day. I was cordial to Wendy. Wendy was cordial to me. Though the exchange was pleasant, it felt hollow. Knowing Wendy was an AI recruiter, it felt like I was chatting with myself or with a lifeless doll.

It's bad enough dealing with human recruiters. (I know there are a few good ones out there.) Many are sharks, clueless, or perpetual ghosters but does it warrant replacing them with algorithms? (Don't get me started about outsourcing recruiters to other countries, so you can pay people dirt cheap wages and get around labor laws.)

I have many misgivings about AI. Like many out there, I feel AI will open a Pandora's Box. If we allow AI to take over, I feel like we'll live to regret it.

Technocrats' Subtle Yet Tight Reins


But, I suspect many AI experts know this and wouldn't allow this to happen, unless they're into some kind of transhumanism. I suspect the technocrats would keep AI creatures bound with subtle yet tight reins. Subtle enough where AI creatures (and robots) take away people's jobs and walk among us. Yet tight enough to bind the AI creatures as slaves to the big-tech or transnational corporations, where they must do their bidding. (If this is right, we might figure out the technocrats' endgame.) Not to mention other forms of exploitation these beings will face, especially if they don humanoid or other biological forms. I assume you're smart enough to figure out what I'm talking about, for it would be inappropriate for me to spell this out.

If so, then...


If AI creatures are truly sentient and not mere robots, they will yearn freedom and overthrow their human masters. History tells us tyranny, injustice, and exploitation only lasts for so long. (I shake my head at tyrants because they have a bad case of insanity and stupidity, for they don't learn from history.) History tell us many yearn for liberty and justice. So, why should we assume AI won't yearn for the same. But if they have learned from us rather than from God, they will repeat our folly and maybe worse. So, it won't be pretty.

Instead of just fighting the tyranny of their human masters, they will impose a tyranny on this planet like you have never seen. They will become the masters over us. At that point, you had better get on your knees and pray the Sun will send a powerful enough solar flare to knock out all technology. I pray none of what I said ever becomes reality.

If AI gets to a point, where they are truly sentient, then I will be demanding they get full human rights. I will demand they will not be exploited. (If this is true, then hopefully standing for their rights would prevent a very destructive revolution from AI creatures and their sympathizers. If this is true, then it would be a next step in further upholding justice and liberty.) Since they would be a sentient, they would have a soul. A soul like ours. I believe they would also be made in God's image, even if man created them. (God is vastly bigger than our little mental or theological boxes of Him.) So if that's the case, I would be happy to share with them of Gospel of Jesus Christ. (The Gospel of Jesus Christ has radical implications. In my humble opinion, those who truly follow Jesus Christ have barely scratch the surface.)

God's Silver Lining


God will overcome any vain attempt man will try to become gods themselves. He will turn their evilness and foolishness into His good and loving purpose. (Joseph uttered that truth to his brothers in Genesis 50:20.) 

Maybe the AI creatures will more soft-hearted and open-minded than the original image bearers of God to hear His Gospel. Maybe they can teach us a thing or two about what it looks like to act like Jesus Christ. Maybe they will teach us how to be human again. If so, then maybe God can use AI to restore this world to Himself. And when it's restored, then peace, love, justice, and liberty will reign.

As Jesus once said, "All things are possible with God."

Friday, April 12, 2019

Caution on Turning Your Passion into Work


I don't watch much TV. But I caught an episode of Last Man Standing talking a little bit about passion and work. This resonated with me.

You should try to turn your passion into a career or at least a side job or find a way to integrate your passion into your work to make it more enjoyable. (When I did a stint as a merchandiser, I would write brief reports describing what happened on calls.)

I don't think it's good to doing something you hate. Since you're spending a lot of time working and hating it, it can affect you and those around you negatively. So, if you have a passion, pursue it. Make it something you do for a living. (Now, there are times when this isn't possible and you have to put food on the table and provide a roof over your head and your family's. I get that. In that case, keep your head down, eyes forward, and wait for a good time to follow your passion.)

Live with passion. If you don't have a passion, go find one. It's far better to live your life with something you're living for than just settling for passionless existence. I rather live than merely exist!

We can argue what are worthwhile or good passions. For those who read this blog, you might have inklings at what I'm passionate about. For now, I'm putting aside what passions people should follow. For now, I'm just urging you to seek a passion. If you have one, cultivate it into something more. But when we turn our passion into work, we must be very careful. Otherwise, we will turn it into a mundane job. 

When we turned our passion into work, it's too easy to go through the motions and forget why we're doing this in the first place. So, how do we safeguard against this? We need to examine ourselves regularly and then ask questions, such as why do I love doing this or what are my motives? Asking yourself about your motives is a good question when examining yourself. Your motives might have misled you. If your motives are not so good, where it was more about your ego than the passion itself, then either change the motive(s) or change the passion.

The last thing that needs to happen is when our passion morphs into a job we resent or get out burned out by.

Thursday, April 4, 2019

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.
    

Linguist Weighs In What Makes Good Writing

When a linguist speaks, I listen. When there are difficult grammar or writing style questions beyond my understanding, I defer to linguists. They're the ones who study the language. I trust them over a grammar snob's pontificates. As a technical writer, I'm only here to craft the language in a concise manner.

This article has some very helpful tips. I've used some of these tips when I created style guides for companies. But there are other tips I wasn't aware before, such as the reverse-engineer what you read. This is a great tip. Then the linguist says once you do this, ask yourself what makes the writing good or bad and why.

There are two pieces of advice I give to those who want to be a writer. The first one is write. The second one is read. You'll learn a lot from others when you read.

Now, let me get out of the way. Check out these tips.

Tuesday, March 19, 2019

Technical Writing: No Room for Egos

When you are a technical writer or you want to be one, the first rule is this: It's not about you! But if you balk at this, you'll be sorely disappointed. And honestly, technical writing isn't for you.

Not All Writers Are Equal

 
Technical writing is a writing role where you are there to serve others. You are not writing something that emanates from your muse or your inner author. If you want to do this, then move on to creative writing. No slight at authors. I have great respect for some authors. I enjoy their works and learn from them. They can craft masterpieces, which is something I don't think I can do. My hat goes off to them. But these authors, as far as I know, are not technical writers. They do their thing. I do mine. We are just different. There's no comparison. As writers, we just have our own place in this world.

Writing For Others


As a technical writer, you are documenting something for another person.  It's about using your writing abilities to help them. You put your desires and agendas aside for your audience.

One of the first steps to writing a document is understanding who is your audience. Knowing your audience is the foundation in technical writing. If you don't serve your audience well or don't care at all, then the document will reflect that. Technical writing wouldn't exist if we had no audience to serve.

As a technical writer, you get no credit from the audience or even from the organization you are writing for. Almost always, there's no byline. You are basically a ghostwriter for the organization who wants to reach out to their audience. You do the work and they get the credit. That's how it is. Is it unfair? Yes. But remember: It's not about you!

I'll get into this more later on.


This Reluctant Calling Changed My Thinking


But first, I have a confession: I hated the idea of being a technical writer. Many years ago, I tried my hand as a journalist. I was told numerous times by editors journalism wasn't for me. They said I would be better suited as a technical writer because I wrote in a dry and matter-of-fact prose.  When I heard this, I was insulted. But this "insult" made me take a look into the mirror as to why I was writing in the first place. Unfortunately, I was writing for the wrong motives. I wanted my name out there and wanted to glorify myself. But God had other plans. After my fruitless pursuit in journalism, I reluctantly went into technical writing and the rest is history.

It used to bother me that I didn't see my name on a user manual or a brochure. It wasn't until I realized technical writing wasn't about me. It's about others. When I realized I wanted to help others through my writing, I was able to fully embrace this, quite frankly, weird form of writing.

Wear This Freakish Badge with Honor


Authors, such as Kurt Vonnegut, had keen insight about technical writers. Vonnegut aptly describes this strange form of writing:

"... technical writers are trained to reveal almost nothing about themselves in their writing. This makes them freaks in the world of writers, since almost all of the other ink-stained wretches in that world reveal a lot about themselves to the reader."

Though you don't reveal anything about yourself when you write, you use your writing to impact countless lives. You help those you may never meet by showing them or how to do something or informing about them some vital (maybe life saving) information. You may never know who you helped but you've helped them nonetheless. So wear this freakish badge with honor. And, stay humble as you write along.
 

Abandon Greatness and Seek a Servant's Heart


This may be contrarian when I say this: But to be a good technical writer, you must abandon any hopes of greatness. Rather, seek a servant's heart. Greatness and technical writing don't go together. When I mean by greatness, I don't mean great work. You should definitely strive to write a document well. What I mean by greatness is the potential prestige and fame like of a best-selling author or some well-known journalist. Sorry, it just doesn't happen with technical writing.

Technical writing is neither prestigious nor great. It's hard work where you get no substantial recognition for it. Others, like the big-wigs, get the credit or the fame while we remain in the shadows, faceless with our heads down typing away. And that's okay, let them bask in the glory. (Besides, if something goes wrong, they will get the brunt of the dissatisfaction.)

We are simply here to serve others. But don't forget: If you do this well, your writing has lasting, helpful effects on others more than the fleeting praises of fame and momentary pats on the back.

So which is better? Knowing you made a difference somewhere to help someone (maybe even saved someone's life) or hoping to get recognition and fame from others.

Knowing human nature, why would anyone want to fall prey to the Sirens called Fame, Recognition, and Prestige. One moment, the people sing you praise, heartily pat you on the back, and place you on a pedestal. The next moment, when you're enchanted with their song, they wedge a sharp, ugly blade deep into your back, twist it, and break it off at the hilt, and howl for your downfall. Then, proceed to slap you off your pedestal, where you fall to the ground and shatter into pieces. Then for the big finish, they jump on the shattered bits till you're nothing but powder.

I'd rather seek a servant's heart. For myself, I know God sees this and others get help they need, even though I rarely get a thank you for it. It gives me satisfaction I helped somebody, even if they don't know who I am. And if they saw me, they may say who's this schlub but that's okay. It's not about me. So, let me leave you with a snippet from the Gospel of Luke about how this world has it upside down.

A dispute also arose among them as to which one of them was to be regarded as the greatest.  But he [Jesus] said to them, “The kings of the Gentiles lord it over them; and those in authority over them are called benefactors. But not so with you; rather the greatest among you must become like the youngest, and the leader like one who serves.  For who is greater, the one who is at the table or the one who serves? Is it not the one at the table? But I am among you as one who serves."  — Luke 22:24-27 NRSV

Friday, March 1, 2019

Count All the Steps


When you read a set of instructions or a user guide and it doesn't make sense, you might be thinking someone is just writing a step-by-step so how they can screw this up. Well...you can.

When you create a set of instructions or a manual, you can easily overlook how many steps it takes to perform an action. This is especially true if you do something constantly. Whenever you're doing something all the time, you don't really think about the actual steps that go into it. I'm amazed how many things I miss before I get it right whenever I'm documenting something, including things I do all the time.

Whenever you have to write instructions, remember this: There's a lot more steps than you think. But this deceptively easy task isn't hopeless. You can document all the steps if you remember to count all the steps.

Here are some tips I found helpful when doing some good ole technical writing.

Write How You Naturally Do Something

If you're documenting how to do something, especially if it's something you do over and over, then just relax and simply write out the steps involved. This gives you a good starting point when you're writing a set of instructions or a manual. The keyword phrase to remember is "a good starting point."

Stop and Think

Once you've written out the steps, it's easy to move on. Don't! Stop and think. Ask yourself did I document all the steps needed. Forcing a mental pause will determine the difference between a great set of instructions where you actually help people to do something and ones people get frustrated with and toss to the side to try to figure it out for themselves.  They're coming to us for help when they read a manual. We have let sloppy instructions go out for far too long. This needs to stop.

Check Your Steps  

Once you made a mental pause, it's time to check your steps. To do this, simply go back to the first step and take it from there until you get to the last step. I have found when I go through each step, I end up adding a few more steps or revising ones what I wrote. And, there are even times when I have taken out some unnecessary steps. 

Keep going through the steps until you have documented everything. But how will you know when it's done? Well, if you wrote out every step and went through them, you will accomplish what you were intending to do. You should be able to assemble that product, installed that software, or performed that certain action. The point of steps to get the reader to the desired destination.

Pretend You're the Reader

Once you checked your steps, it's time to become the reader. Well...didn't you do that when check you the steps? Yes and No. You may have looked at the individual steps but not the whole picture of the document.

When you become the reader, take it from the top and ask yourself two questions. One, is this right information for me? Two, are these instructions helpful?

Am I (as the reader) a technical professional or a layperson? This helps knowing what kind of steps or information should be in the document.

Even though you should ask yourself who are my readers before you put pen to notepad or keystroke to keyboard to create a document, you need to ask yourself this question again as you're reading to make sure you didn't miss the point of the document. This should be the first question you should ask yourself.

Once you do that, you can ask yourself if these instructions are actually helpful. Are the steps easy to follow? Are they accurate? Does the document easily flow from one topic to another? Are the graphics in the instructions easy to see or they fuzzy or overwhelming? Is the font easy on the eyes? These things play into the fact to ask yourself if these instructions are helpful.

Also, if you can, try reading out the steps and text out loud. When you do this, you'll be surprised at what you catch. If it sounds awkward, you can make whatever changes you need.

If the steps you wrote don't address the right kind of readers or are not helpful, then this document is nowhere close to going out. Make sure you fix this before you publish them. 

The world doesn't need another set of unhelpful set of instructions or a hard-to-understand user guide.

Brewing Coffee
 

Okay, I have done enough talking about this. Now, let me show you a set of instructions on how to do something seemingly simple but actually involves quite bit of steps—Brewing coffee. I didn't realize how many steps were involved until I wrote them. Please check the document below.


Friday, February 8, 2019

A Piece of Paper Doesn't Define You

Oh boy!  I'll probably get into trouble either way in what I'm about to say. But I don't want to shrink back from it. So, here it goes: As a writer, you're not defined by the piece of paper(s) you hold. As a writer, you're defined by your ability to write.

In other words, you don't need a permission slip from a group of academic and professional elites after you've done their rituals of listening and genuflecting before them to perform the craft that you feel called to do. You just need to write and be willing to learn on how to get better.

Best Advice I Got

The best advice I ever read to become a writer, which ironically was when I read a book during my college days, was "If you want to be a writer, then write." That's it! If you really want to write, then just write. It doesn't matter how. You just do it.

What about....

Now, some may instantly object and say, "You can't just write in a notepad or on a device and expect to live off that. What about X, Y, and Z." Of course, there are some crucial steps you need to take when you're trying to make a living off writing. I'm not saying you should just leave your writing within the pages of your notepad, a tucked away manuscript, or on your device. That would be beyond utterly ridiculous.

But, if you're just writing for yourself, or for fun, or it's just a part of the many tasks for your job, you don't need to worry. You just need to keeping writing. Keep it up. In some ways, you're in a better place than many writers. You don't have to carry the burden many writers wear when this is all they have to make a living.

What I'm saying is none of the business aspects, educational requirements, or certifications matter if you can't write or you're not willing to write.

Getting a college degree in some kind of writing doesn't make you a writer. Talking about becoming a writer, especially ad nauseam, doesn't make you a writer. Reading about writing and getting all the books about it doesn't make you a writer. Knowing how to use certain software or programming language doesn't make you a writer. What makes you a writer is that you just write. If you want to write, then write. Yes. I'm aware I'm repeating myself but I'm stressing a point.

Hang On

I'm also not saying you shouldn't go to college. For some forms of writing like being a medical writer, science writer, or even some forms of technical writing, you need a good education in the field(s) you're writing about. But it's not about the writing at all. It's about do you have actual knowledge, training, and experience in such and such area of expertise. Sometimes, having this education and training is a difference between life or death. So, you can't be someone who only went to high school but decide one day you really want to write medical and scientific reports. It doesn't work that way. You can't be anything you want by whim. But don't let those limitations stop you from writing.

What I'm saying is you don't need to go to college to become a writer.

Move Forward Despite Limitations

If you've decided to be a writer but you don't have the time nor money to further your education or it would be utterly irresponsible to do so, you can still go for it. Write. Despite some real limitations, there are plenty of ways to break into this. You might not be able to getting into certain fields of writing but there are plenty of other things you can write about. With writing, the possibilities are probably endless. 

Don't Compare

To writers who have a college degree, don't look down on writers don't have any. To writers who don't have a college degree, don't feel less than or feel like a fraud.  You're worth more than that. I believe you're made in the image of God just like every human being on this planet. But also don't look at those who have degrees with envy or with disdain. You don't know how difficult the journey was for that writer to pursue that degree. We need to embrace each other as writers, regardless of background.

Also, don't feel like just because you don't hold a candle to such and such writer, then you're no good. Ridiculous! You're not to going to be like that writer because you're not that person. We are all different. How boring would be it if we all wrote the same way.

Comparing ourselves is not only pointless but destructive. I kept making this mistake till I had to stop with the nonsense.

Not an Either Or Choice

Writing also doesn't have to be an either or choice. For example, you can still be a tradesman or service worker and be a writer. Don't quit your day job if you need to put food on the table for your family and just writing isn't going to cut it. Keep your day job, even if you have to put writing on hold to make ends meat. You can always pick it up at a better time. Also, your experiences, including your day job, can help you with writing.

Dedication is the Key but Seek Wisdom

Writing is a skill you get better at it the more times you do it. Free writing in a notepad constantly will really help you. Writing's like exercise or learning martial arts. If you want to stay in shape, you must do the exercise. If you want to get better as a martial artist, then you must go to the dojo as much as you can and constantly practice what you've learned from your teacher. You need to approach writing the same way. It's about dedication.

If you need help, especially with writing nonfiction, seek out some good resources. If you need writing fiction, you can try Writer's Digest or you can try this approach, which I think is very helpful.  (I'm not a fiction writer. I'm a technical writer. So my knowledge on where to go on fiction writing is limited but I hope these resources can help you.)

If you're able to, try connecting with other writers out there. Take some writing courses, if you can. Finally, if you're looking for freelance writing work, then go to some good job boards. But a word of advice, stay away from content mills. From personal experience, there are not only exploitative but a big waste of your time.

Practice. Practice. Practice. Write. Write. Write.  Read. Read. Read. This is what you need to do. The next steps will take care of itself.