Technical Writing: Systematic Advantage

When my wife and I watch campy movies, there's a typical theme of a writer who has writer's block. The writers in these movies try to write something but can't. Or when they start writing on the computer, they let out a sigh, deleting everything till it's a blank screen. While these scenarios are exaggerated, there is some truth to it.

It's difficult when you must create something that relies on your mind. I know. I've written a novel before. Writer's block is always lurking around the corner. When you write, that constant inner critic is always trying to lead you to that corner. Those who are career authors, I don't envy them. God bless them for keeping their imagination going, though they struggle to craft meaningful words on the pictures they're trying to paint.

We technical writers have a systematic advantage over our creative counterparts because we document things based on what we can see and use. (I mean systematic, not systemic because while the writing process is universal, we're in a different category than creative writing. I suppose you could say we have a systemic advantage. In any case, we have an advantage.) If you're documenting user interfaces, we can walk through each step of the way to help us write. So the chances of writer's block decrease, though it can still happen.

Should we feel ashamed that we do have this over other writers? Absolutely not! But we should be thankful that we don't have those blocks. Of course, our blockers are from SMEs, developers, or whatever. We can't write anything until they're removed. But once we remove these blockers, we are to free to write till we're done. Our blockers are external not internal, so we have an advantage. So let's use it to create great documentation. Since we don't suffer writer's block like the creatives, there's no excuse for sloppy documents. Am I saying perfection? No! There's no such thing as perfect documentation. But we can strive towards excellence.

So, my hat goes off to you creatives for doing what you do. Keep writing! Thank you for building those worlds for us to enjoy and think about.

 

Whose Glory?

"So, whether you eat or drink, or whatever you do, do everything for the glory of God." – 1 Corinthians 10:31 NRSV

Though I strive to uphold this Scripture, it also makes me pause. Whenever I'm writing, whether it's a story, documentation, or this blog, this nagging question echoes in my mind: Whose glory am I doing this for?

Then, the answer comes or follow-up questions come. Am I doing this for God? Or am I doing this for myself? And if I say I'm doing it for God? Am I really? Or is that a convenient excuse I give myself to do what I do.

No matter how hard we try, we can't avoid this question. So we must honestly answer it.

This question isn't only for writing. It's everything. So why is this question important? Well, it'll steer us toward why we're doing something, including technical documentation. 

On the surface, technical documentation seems to glorify the organization. The organization tells its audience they have the answer they are looking for. If its audience is grateful or in awe over the information, the credit goes to the organization. But who wrote the documentation? If you're a technical writer for an organization, you wrote it or those on your team did it together. 

Now, if you believe your organization is the best and you're truly writing for it, then, by all means, do so. But are we deluded ourselves? Isn't there something we get out of creating technical documentation? Isn't there a sense of accomplishment or pride? You may be a better person than I am. When I create and deliver technical documentation, I get a rush and the satisfaction of a job well done. It's a great feeling when I get stellar feedback.

So, on some level, I'm creating technical documentation for my glory. Even when it's a team effort and I happily give credit where credit is due, I still get something out of being a part of a bigger effort. Also, I enjoy creating technical documents because I like helping my audience clearly see the answers they're looking for. Though I want to use technical writing to help put food on the table for my family, I like the feeling that I'm doing my part. So it seems inescapable that I'm doing all this for myself.

If we're completely honest with each other, you would say the same thing. So what do we do? Do we just admit we're really narcissists and live that out? If so, see where that takes you. Or do we strive for something better? 

I think the better road is to acknowledge this selfish element and strive to create documentation for God and others. Like writing, striving for this is a life-long goal. Even if we're far from this, it's worth pursuing. 

Though I'm far from perfect and I don't have it all figured out when I've asked God to help create documentation for Him and others, He has helped me create something far better than I could've imagined, especially when I've collaborated with rockstars in their fields.

Honesty with this question is the way to move forward. But be careful! It might lead to other questions, such as: Is this something we should be doing? If not, should we do something else that's not for ourselves? This includes technical documentation. 

To deepen ourselves in our trade, we must reflect on why we do what we do. Whose glory? Us, others, God?

When you Doc as Code

What is doc as code? Doc as code is basically two things. One, it's creating documentation with the same tools as you would use to create code. Two, it's using similar methods of creating, versioning, and publishing documentation as you would with code. 

What do I think about this? Short answer is context. If you're creating or editing material in a software environment that uses Agile methodology, then you should doc as code. Otherwise, I wouldn't worry about it. If you're in this context, I'll give you a few,  brief reasons why you should doc as code.

Save Costs

The first and foremost why you should doc as code is to save costs. Tools, licensing, even training on how to use tools all cost money. It also costs time to maintain and invest on different tool sets. If you're using the same tool to create code and documentation, you can save on both. No further explanation needed. 

Easier to Build Bridges

If you're using the same tool as your Subject Matter Expert (SME), it's easier to build bridges to create documentation. If you're using the same tool(s), it's easier to collaborate together on documentation. This doesn't mean you have to learn to code. (But it might help to know a little bit.) In some ways, using the same tools and releasing documentation the same way as code is like you're speaking the same language as your SME.

More Unified Experience

If you doc as code, then the release of software and documentation is much easier. The obstacle of getting your documentation in a certain format, so it goes with the software release is no longer an issue. You just have to make sure you and your SMEs are working in sync to make sure the documentation reflect what's in the code and vice versa. And that can be challenge in itself, so why would have other unnecessary issues to prevent this from happening.

To find out more about doc as code, check out these resources:

https://www.writethedocs.org/guide/docs-as-code/

https://www.gitbook.com/blog/what-is-docs-as-code

https://github.com/readme/guides/code-as-documentation

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.