Grateful For This Blog

I mentioned this before, but sometimes it's worth restating. No matter how much blood, sweat, and tears we pour onto technical documentation, it's not ours. Those who of us who are technical writers are just hired wordsmiths for someone's else product. They can take the credit for it, even though we have labored on creating or editing clear documentation that presents a message for their audience. Without us, their customers would probably be confused on they offer or how to work their stuff. (Now, there's really bad documentation out there that's confusing that does this anyway. But that's another discussion for another day.)

When I first became a technical writer, the most stinging part initially was I had no byline. The document's byline was the company's. But I realized over time: It's not about me. It's about the company I represent and their customer. God has continued to use technical writing to show me of this fact. 

I would be lying to say I'm totally okay with this fact what we write isn't ours. But I can also say I have embraced this fact and it continues to make me a better writer. I realize what I do isn't about me. Sounds like a contradiction. It's just a lifelong process of accepting this.  I'll let you decide whether I am contradicting myself.

I have this blog because it's something I can call my own. I don't care if it gets a lot of traffic. I don't care to be famous. It's overrated anyway. I just wanted something where I can showcase my writing style. I am grateful for it. I also use it to help those who are on their journey with technical writing or even just writing in general. We are all writers, regardless of our stripes.

But ultimately, nothing I write is my own, not even this blog, my novel, or anything else I write. It all belongs to God. What I do should glorify Him. Technical writing just helped me see this eventually.

“(A Psalm of David.) The earth is the LORD'S, and the fulness thereof; the world, and they that dwell therein.” -- Psalm 24:1 KJV

Not All Writers Are Equal...And That's Okay

Different kinds of literature are everywhere. That's just a fact! Whether it's a fantasy or sci-fi novel, historical fiction, a book on historical events, biography, memoir, or even ad copy, UX writing, video game writing, interactive fiction, blog posts, reviews, or a news article, we see different forms of written work out there. So what's the point in stating the obvious? 

The obvious is just because you're a writer doesn't mean you can write every form out there. I suppose you could. But are you going to excel at it? Are you truly passionate about a particular subject or genre? Do you have previous expertise in a particular field of knowledge or at least willing to learn that field? Or, is this for a paycheck or creating a vanity project? Any writer who is serious should honestly ask themselves these questions.

To be fair, there are some writers who do great writing at different genres. God bless them for having this ability. Writers, such as CS Lewis, who wrote both non-fiction and fiction was great at what he did. I have been blessed from what he wrote. And writers, such as Harry Turtledove, has been successful creating many different types of novels, especially alternative history and fantasy. (I have yet to read his alternative history stuff, but I would like to. I've only read his fantasy work thus far.)  

And, there are writers who write for a hybrid of genres. For example, the technical copywriter has to dance between writing engaging marketing copy and explaining technical information clearly. Talk about a feat!

For others, such as myself, I excel at one area–technical writing. I don't consider myself that good.  I just simply do my best to create clear, accurate, easy-to-follow technical documentation. (I have written a novel, but it seems I excel as a technical writer instead. Whether I write another novel, well, that's to be determined.) For me, creating technical documentation is as natural as breathing. Even though it's still hard work, after all these years, it's a labor of love. I like guiding people through complex topics or helping them learn how to do something. 

Not everyone wants to do what I do and that's okay. I don't picture myself writing ad copy, alternative history, high fantasy, or even a treatise either. And that's okay too. 

I let the other writers who are more skillful than I do that. As much as I love to write, I also love to read and appreciate a good book. If I'm able to incorporate elements of their work into my niche, then great. If not, I can just appreciate at what they do, the story they're telling, and learn from them.

God has created a big enough world for us to live in and includes us writers. We don't need to feel squished out by other writers or have to write every form there is out there. We don't need to sound the same. Each writer develops a particular voice over time. I can't explain this. It just happens the more you do this. 

If you're a writer, or you're trying to get into writing, ask yourself these things: what things interest you, where do you feel no one is writing about, or what needs can I fill? If you were to ask me, I would tell you to pray about this and see where God leads you. If you take the first step, or the next step, as a writer with this mindset of asking yourself this, you'll find where you need to go.

Not all of us writers are equal and that's okay.

Some Cliches Still Have Power

With writing, especially technical writing, we're supposed to get rid of cliches. Why? Cliches have been so overused where they lost meaning or power. Yet, if we're honest, we communicate in cliches at times because it best captures something we're trying to say.

The cliche "the pen is mightier than the sword" is true because written works have brought far more change in this world, or destruction in some cases, than any armed revolution or army could ever do.

Even though I'm just a technical writer, I feel humbled to be a part of a craft that has potential to change the world.

Not Just Halloween 

Today, is Halloween also known as All Hallows Eve. However, on this same day, it's

Protestant Reformation Day.

Martin Luther, an Augustinian monk, saw the abuses of the Church in his day, where it was more about money and power than about love and grace of Jesus Christ. He was so disgusted that he had to get the word out about these abuses by posting his 95 theses on the door of the Wittenberg Castle Church.

And from there, whether for good or for ill,  Martin Luther altered the course of the Western Christian Church, Europe, and eventually good parts of this world.  (If you want to read an in-depth biography about Martin Luther, I recommend Derek Wilson's Out of the Storm.)

Now I'm aware that Martin Luther wasn't perfect. They were things that he said that I'm still scratching my head to this day. But people and their written work don't have to be perfect to affect the world.

When the time and conditions are right, written works are the sparks that set the blaze of change to consume the world.

The Book that Affects Change

But I would be remiss if I didn't mention the Greatest Written Work that has permanently changed the world, the Bible. 

The Bible is the most controversial book known, yet it still changes lives. Empires have fallen. Nations have changed and gotten liberated from their oppressors. Slaves have been set free. People have died over it, especially those who want to get it in the hands of the common people. It has been demonized, mocked, and has polarized people. Wars have been waged over it. Sadly, it has been the most abused written work to justify evil behavior and hatred. Yet, the Bible has been used to stand for justice, liberty, and love. The Bible has the power to affect the world. God said this about His Word:

‭‭Isaiah‬ ‭55:11‬ ‭ESV‬‬

"...so shall my word be that goes out from my mouth; it shall not return to me empty, but it shall accomplish that which I purpose, and shall succeed in the thing for which I sent it."

What is the Bible? In a nutshell, it's God's story of salvation for humanity and Creation. After He created the world and people and they rebelled against Him (Genesis 1-3), He set a plan to redeem what was lost back to Himself. If you keep these following verses in mind till you get to the end of the Bible, you will see how God's plan of salvation comes together:

‭‭Genesis‬ ‭3:14‭-‬15‬ ‭ESV‬‬

"The Lord God said to the serpent, “Because you have done this, cursed are you above all livestock and above all beasts of the field; on your belly you shall go, and dust you shall eat all the days of your life. I will put enmity between you and the woman, and between your offspring and her offspring; he shall bruise your head, and you shall bruise his heel.”

The Bible is the written work that has changed and continues to change my life. If you want to know the Bible for yourself, then check it too. You won't be the same.

Thank you for stopping by. Happy Reformation Day! Happy Halloween! God bless!

Simple yet deep (or difficult)

When I was choosing a vocation, I just want to do something simple, yet take a lifetime to grow in it. Writing seem to fit. Writing is actually hard, even if you want to get good at it. I don't claim I'm a good writer. I just happen to enjoy it, and God continues to bless me with a career in technical writing.

Writing is not perfection, which I think is the core problem of writer's block, it's about the process. And the process is one that I enjoy and find it a privilege to continue be a part of.

Simple, yet deep (or difficult) is the essence of the writing craft. It sounds like I'm contradicting myself. But, hang on. If you want to be a writer, you just write! Don't think about it! Don't talk about it. Just do it! That was the best advice I got when I first started my writing journey. It's been difficult along the way. But to start was simply just to commit my first word on paper (or screen) and go from there. The deep, many times difficult, is where you continue to grow and improve your craft. The initial draft is easy because it can be poor, disjointed writing. (That's not to say, it's always easy. I continue to struggle with an initial draft. But it doesn't have to be hard.) The hard part is the rewrite and edits to take your writing to the next level. 

I guess we can say the writing craft is a paradox. And it's a paradox worth diving into. It takes tenacity to swim through this paradox. When coming out on the other side to see the finished product, it was worth the effort.

Simple enough to start, yet deep enough (or difficult enough) to develop. That's writing in a nutshell. Or if you're like me, that's technical writing. Thank you for stopping by. God bless.

When you don't have all the pieces

When you create documentation, there are three fundamental questions you need to ask.

1. What is the thing you're trying to document?

2. What kind of document are you writing?

3. Who is the audience for this document?

If you get answers to these questions and find the key Subject Matter Experts (SMEs), you're on your way to creating good documentation. But let's be honest with ourselves, even with this information, there's a good chance that you'll still have missing pieces. What do you do then? 

If you're in a circumstance, where you can test the product, say software or API calls, then you can probably fill some of the missing information. But not all technical writing circumstances are the same. Sometimes, we're detached from the subject we're writing about because we're not able to test a product. Going on a limb here, say nuclear technology. It doesn't have to be this extreme. But it could be just simply no way of testing out your subject or product. So what do you then?

One thing you can do is be persistent. As you talk to the SMEs, ask your questions along the lines of the fundamental questions you've asked initially. When SMEs are stumped from your questions, you can ask them who would know. They might direct you to another point of contact or get back to you if they need to dig into this. In any case, finding the missing information for a documentation isn't impossible. It just requires persistent. 

The worst that can happen with documentation, is that you can't write it, because the information doesn't exist and maybe the subject just a concept for now. And that's a planning issue beyond the scope of your responsibilities. Aside from this, if you're persistent you can find the missing information.

It reminds of the game Chrono Trigger with mysterious gray chests scattered throughout in different places and time. When you try open them, it would play a song and a dialog box tells you a mysterious force is keeping it locked. You can still play the game but it seems like something's missing when you can't open these chests. These chests stay locked until you charge up Marle's perdant and that's when you can open these mysterious chests.  

Like the way you need to charge up Marle's pendant to unlock these chests, you just need to find that piece of information or point of contact that help links the missing pieces together. Creating documents can be an interesting quest.

QA Your Docs: Final but often rushed step

Once you've written the docs, it's time to release. Right? No.

Other Technical Writer: But I double-checked the text and the graphics to make sure it looks good. 

Me: That's great. You looked at the docs and made the edits. Editing is step 4 in the general writing process. Every step in the writing process is crucial. But did you QA the docs? 

Other Technical Writer: QA? 

Me: Yes, did you QA?

Other Technical Writer: What do you mean by that? Do you mean I sent the doc to QA? 

Me: Well, you can do that and probably should if you have QA people. But did you QA the doc yourself, especially if you have the ability to do so. 

Other Technical Writer: Well, how do you do I that? 

Me: QAing your documents just means check to make sure the steps you wrote is matching the product is doing. In other words, does your document correspond to reality?

Often Overlooked Step

If we simply take the time and check to make sure the document is actually saying what the product is doing, then it might avoid dissatisfaction from our customers. How beyond annoying is it when the instructions are not only confusing but also don't correspond to the actions or parts of the product? This is probably why many chuck the instructions and try to figure it themselves. For a lot of things, someone can do this just fine. And the instructions are just stupid and useless. But what if those instructions are critical? And, if they try to do this themselves, they and others might get hurt–or killed–because of poor documentation. 

Instead of rushing things and slapping instructions together, let's simply take a little extra time to make sure the documents accurately portray the product. Faster isn't always better. It reminds me of this Scripture, especially the latter part of the verse:

"It isn’t good to have zeal without knowledge, nor being hasty with one’s feet and missing the way." -- Proverbs 19:2 WEB

A well written but inaccurate document is completely useless and should be tossed in the trash. A useful document has both accurate information and simple writing to clearly explain it.

How Do We QA a Document?

To QA a document, just walkthrough the document to verify what it says matches what the product actually does. When it doesn't, then fix the language or pictures until you go to the end.

If you feel it's too daunting to go through the entire document in one go, then you can QA a section after you finished writing and editing it. You can also go through the document in chunks until you're done. It doesn't matter how you do it. What matters is that you QA the document before you release it.

If we take this final, but needed, step then we won't miss our way.  If someone is preventing you from taking this step, push back if you can and tell them to wait until you're done. (Of course, the product and its documentation should go out the same time.)

It's better to take our time and put out documentation at a reasonable time, then rush it out the door and you'll have to deal with a bunch of problems after.

More Thinking, But Don't Overthink

What if we thought more before we said or wrote anything? I like what Warren Buffet said about how spends his time thinking. This sitting and thinking can come in handy as technical writers.

Before we create documentation or in the process of creating one, it might help to stop and think things through. (This will especially be handy if you have a product to play with.) We might get clarity as we walk through a mental journey to overcome some huddles. 

Save Time and Effort

Thinking more might save you time and effort on documentation. Rather than fuddling around where you might end up deleting either half the documentation or the whole thing, why not think things through before you write? Jotting some quick notes can help you see where you need to go. (While I believe deleting what you wrote previously is a part of the writing process, there is such a thing as overediting, which I think is a part of overthinking, which I will get into in a bit.) Thinking can help you create a map of where you want to go or prevent taking unneeded steps. 

So, if we were documenting a product and we had it in our head initially to create one giant document, but then as you think it over, it turns out it would be better to have a series of smaller documents. Or, let's say you thought at first you need multiple documents but you realize only need one document. Or finally, the product is so self-explanatory, it doesn't need documentation at all, so you can focus your efforts elsewhere. 

Thinking things through can help us with this, rather making rash judgments where we'll regret this later. We only have so much time in our lives, so we need to be prudent with what we do.

Writing is Thinking–Probably Not

Some might contend that "writing is thinking." I see what they're saying. I agree with this to a point, but in the end I have to disagree. Writing and thinking are two different things. Thinking is a mental process in your head. Writing is a creative process that shows itself in print, audio, or screen. Thinking may help you get ready for writing but it's not writing. If you think otherwise, that's fine. We can agree to disagree.

Don't Overthink, Just Write

Just like you can overwrite or overedit something, you can overthink something. Overthinking is bad. Like over-engineered or overwritten work, it can be confusing at best, where you have too many caveats, complexities, or features. At worst, it can lead you to a mental paralysis where you can't write anything at at all.

After thinking something through, it's time for you to write and let the chips fall where they may. When it comes to writing, I agree with Ray Bradbury. I like what he said about writing. In context, he was referring to creative writing. But I think we can apply this to technical writing. 

I have seen other technical writers, and I've experienced this myself, paralyzed to create documentation because we overthought stuff. We were trying to take too many things into account. When we commit to writing, we just need to need write it out, refine it, and publish it. Worst case scenario is we need to revise the documentation. Revising documentation is a part of life as a technical writing. This is especially true if you write for software applications, where updates are the norm.

But first, what if we sat and thought carefully, without overthinking, through things before we did anything? I wonder how life would be?