Search This Blog

Wednesday, July 15, 2020

What's the Point of Writing

My goal as a writer is to clearly communicate a point to another. If I can do that, then I accomplished my goal as a writer. Everything else that entails writing is just gravy.

This should seem obvious for those of us who are wordsmiths. Others who practice this craft, who are far more skillful at this than I, might give a different or a much more articulate or more insightful goal than what I just wrote above. But, let those write out their own goal for writing. I'm just speaking for myself on what I want to accomplish with writing.

But what is writing anyway? Writing is simply communicating a thought in written form to another. It could be writing to yourself but that's still communicating a thought in written form. That's what writing is about. What about poetry or creative writing? If we boil it down, it's still communicating a thought or a point in written form. I'm not dismissing these beautiful artforms. (I have even delved into this form of writing by creating and publishing a novel.)  I'm simply making the point writing is a means of communicating of what's inside your soul. 

But this gets tricky when we're talking about business forms of writing. In that case, you're communicating what is inside that organization's soul (ha, ha) and we're just facilitating. At least, that's my take from experience as a technical writer. If we are writing in a business setting, then it would be know if that company's values match your own because as a writer you are communicating in the heart of that company.

Where am I going with this? I believe it's important to know why you're writing. What are we are aiming at? Writing for simply writing's sake is a waste of time. That's like firing an arrow without a target in mind. That's only dangerous but pointless. When we write, we must know where are writing for and why. 

Of course,  I don't merely want to write to make a clear point. I want to make that point to help others with whatever it is they need help with. And of course, the point should be honest. But, I won't be able to help that person with honest information unless I make a clear point.

What about passion? Yes, you should definitely write because you have the passion to do so. If you don't have a passion to write, don't bother. Otherwise, it will show.

So, I stated my point for writing. What's yours?

Thursday, May 7, 2020

Mark Up the Screen with Markdown

Markdown Logo
When it comes to writing on a device or a computer, I want something simple that allows me to focus on writing yet powerful enough for me to create full-on documentation or a book. Markdown fits that for me.

Markdown is a markup language that's basically simplified HTML. You just focus on writing without the other stuff and the rest follows.

There are different flavors of Markdown, such as kramdown. But, it's still Markdown. I have used Markdown to create some documentation or to communicate on a project's status in GitHub. When I did that, it felt pretty freeing to focus on what I wanted to say. Creating Markdown files in Atom for some documentation was pretty fun too. 

I'm even using Markdown to create an early draft for my next book. 

If I had my druthers, I would create all technical documentation in Markdown. I wish I could just do all my technical writing magic in this markup language.

Anyway, here are some places to get a good understanding on Markdown. (Thank you, John Gruber for creating Markdown. I appreciate it.)

I hope this aids you in your journey. Keep on writing. 

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."