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

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

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

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

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

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

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

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

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

My Story: Creation of a Style Guide

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

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

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

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

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

An Alternative Way of Explaining

In case you don't know, alternative text (alt-text) is text that describes images for the visually impaired.  As more people access and read electronic documents or online content, this isn't a nice to have. Alt-text has become somewhat essential. In some instances, especially when you're creating documentation for the government, alt-text might be required. So, technical writers must have this awareness of creating alternative text under their tool belt. 

How I became aware of using alt-text

My awareness of alt-text didn't come at once. It was gradual. Years ago, I worked with a colorblind graphic-designer on a short-term contract. He told me to change colors on some graphics in the documentation so those who were visually impaired would be able to see them better. This wasn't about alt-text per se but it got me on the road to try to open documentation to all people. 

Some time after, companies would ask me if I knew 508 compliance or knew how to write alt-text. At that time, I said I didn't but said documentation needs to be accessible to all.  Since I didn't have this knowledge, they'd pass me by. So, I looked into alt-text and 508 compliance standards. Eventually, I was blessed with a few short-term contracts where I was able to write accessibility text (synonym for alt-text) and use 508 compliance in documentation. So now, when possible, I write alt-text in documentation that I create. 

How to write alt-text and do tools support them

If you're unfamiliar with how to write alt-text, it might seem overwhelming at first. So here are some tip to write alt-text.  

• Put yourself in the shoes of those who are visually impaired. How you want someone to explain this to you if you couldn't see well or not at all. In other words, enacting The Golden Rule. If you follow The Golden Rule, you'll be able to write great alt-text.
• Write brief, succinct descriptions of the images you're describing. 
• Write 1-2 sentences for most cases. One sentence is optimal. The exceptions would be highly-detailed flowcharts, infographics, images, or screenshots. In those cases, you may write a few more brief sentences but I wouldn't go past that.   
• Don't start with intros "This image shows..." or "This is a picture of..." That's condescending. Just state what the image is. For example, if you have an image of a boy petting a German Shepherd. Just say "Boy pets German Shepherd."
• Don't write alt-text for decorative images. Only write alt-text for images that convey actual information.

But do tools allow for alt-text? Short answer is yes. Most tools out there have a way to easily put alt-text. If you need help, see the help documentation of the tool(s) you're using. (Some tools now automatically put in alt-text. But check your tools if they do that. Personally, I'd rather write alt-text instead of letting the tool do it for me.)  Now, if the tool you're using doesn't have an easy way to add alt-text, check for workarounds. 

Alt-text resources

To get more acquainted with writing alt-text, check out these links. The information in them will help you go a long way. These links have helped me whenever I need guidance on how to write alternative text. 

• Authoring Meaningful Alternative Text
• Write helpful Alt Text to describe images
• Examples of Alt Text
• WebAIM
  
• Alt Text: What to Write

Don't beat yourself up if you don't get alt-text principles right away. If we technical writers are honest, we're still learning on how to write good alt-text. Remember, it's not about you. It's about helping those who can't see well or can't see at all. If you're a visually impaired technical writer, we value your insights. We need your help on how better write alt-text. Like all forms of writing, crafting alt-text is a process and journey to become better at it. If you're brief, succinct, and you follow The Golden Rule, you're on the road to create crisp alt-text. If you continue to master the art of writing alt-text, you're capturing the essence of great writing. 

Why I'm Not Afraid of AI

AI. Artificial Intelligence. It's either met with excitement or with fear. In any case, it's been the conversation piece for many. My understanding of AI has grown since I've first wrote about it. But this post isn't so much about AI. (There are plenty of experts out there who can tell you all about it.) My post is focused on why I'm not afraid of AI.

Tentative Stance

Before I get into why I'm not afraid of AI, here's my tentative stance: Artificial Intelligence isn't some nefarious overlord or a cabal of overlords plotting to dominate or exterminate humanity but it's also not some passing techno-fad that'll vanish anytime soon. Think MiniDiscs.  If we think about it, Artificial Intelligence has already been with us for some time. Think spelling and grammar checkers or chess super computers.

Because of its seemingly endless potential, like the Internet, Artificial Intelligence continues to transform and help us find better ways to do things. But in the process, this might include making certain jobs obsolete. Sadly, this happens with every technological innovation. But only God knows the future, so AI's continued existence is yet to be determined. Since we're in the present, we need to face AI and know how to move forward with it.

AI and Writing

AI may be able to correct spelling, grammar, and write text. It might be able to produce huge tomes. But I don't think it'll take over documentation and make technical writers obsolete. I'm not afraid. Why? Documentation. Well, good documentation needs human nuance.

Human Nuance

What do I mean by human nuance? And why will AI never replace it? Human nuance is just discernment. It's been able to go beyond the surface and dive deep and note the differences. No matter how advance AI becomes, it won't fully know what to include or leave out in documentation. When it comes to writing, it can't do what Mark Twain said. Only a competent writer knows how to do this. Artificial Intelligence also won't fully know the audience, so its aim will be off when if it writes documentation. Algorithms can be helpful but they fall short. Only a technical writer or an SME, especially those who talk to their customers, truly know the audience. 

AI also won't fully know how to structure the information in documentation.

Good documentation goes way beyond well-crafted prose. (If that were true, AI could replace us technical writers. But that's not the only factor for good documentation.) What can make or break a document is how you order information. You need a logical or natural order to make a document flow. Let's not forget one more ingredient to documentation: creativity. There's always an element of creativity involved when designing documents, especially when it comes to its flow.

AI can't do any of this. Why? It's not human. We're humans and write for humans, not for machines. We write to humans to show them how to use a tool, software, or machine.

AI is just a Tool

AI is a tool. It doesn't matter how powerful it's becoming, it's still just a tool. This is no different than huge tractors or industrial drills. They're powerful and have allowed us to do far more than before they were created. But despite their power, they're useless if no one wields them. The same goes for AI. If no one uses it, then it'll just sit there. It doesn't matter how it advanced as it continues to evolve. It's just a tool–a useless one at that if no one uses it.

How ridiculous does it sounds to run away from hammers, screwdrivers, and power saws because we're afraid they're going to replace us. So why do some have this kind of fear with AI?

You can laugh and say I'm naive or I've drank the Kool-Aid (actually Flavor-Aid) of the technocrats who are pushing Artificial Intelligence. No! Quite the opposite! AI is overrated! It's powerful but it's just a tool! So, it has no power if no one uses it.

Rather than running scared, thinking it's some virtual, evil demon who seeks to master us, we should grab a hold of AI and make it submit to us to do what we need it to do! Rather than getting worried whether Artificial Intelligence will replace us technical writers, if the AI revolution continues, let's use it in our favor to augment our abilities to create good documentation.

Could AI cause a lot of harm and destruction? Yes! Absolutely! But so can cars and knives if they're wielded by very bad people. Since AI is just a tool, it matters how you use it. So, if someone misuses it, don't blame the tool. Blame the user! 

Also, letting AI run unchecked is a bad idea. That's like just leaving a wood chipper on! It shouldn't take much imagination to foresee how many problems can happen there. You don't leave tools on after you're done using them. But if they need to constantly run, we must have guardrails in place. Common sense should kick in here.

AI Depends On Us

AI is living on borrowed capital. That capital is us. It only has a semblance of forming thoughts and worldviews because it depends on the information, thoughts, and worldviews that we had before it existed. AI is incapable of forming anything outside of the human experience. If it's reluctant to die and fights to survive, as some have reported, this shows a very human nature. And how that nature come about? It came from us.

Let's play the worst case scenario 

What would happen if it becomes smart enough to try to dominate or worse try to kill us? That's a valid concern. But let's walk through this. Let's say AI succeeds in killing us off. AI will then have nowhere else to go. Its growth will stop. At very best, it may try to war against other Artificial Intelligence and either take them over or destroy them. And if there's only one AI on this planet, then it'll run itself into ground. It'll hit a dead end because there's no human interaction.

What if tries to go to other planets? It won't happen or it won't succeed. Will Artificial Intelligence build starships to reach the cosmos? If it can, will it desire to do so? Only human ambition, though sinful it can be, fuels that desire to best, expand, exploit, and take over everything. It may replicate this desire but why? There wouldn't be an incentive because AI will always despite, how advance it gets, will always be in a closed loop of itself. Why? AI's a tool! And if AI builds starships to seek expansion and colonization, well...good luck. It'll be stuck with just the technological information that humans possessed before it murdered them.

Human interaction is the lifeblood of AI. If AI kills us, it kills itself. 

Now let's say AI doesn't desire to kill humanity but enslaves because it knows it needs us to survive. People will eventually overthrow it directly or use fake, nonsensical information to sabotage all Artificial Intelligence. AI is not a god! AI is just a tool! Like all tools, especially ones that won't work properly or get out of hand, there's always a way to shut them down or get rid of them. Stop feeding it electricity will knock it out. Many humans, by nature, have a rebellious steak when put under the thumb of others. Throughout history, this has been a double-edged sword. Though sin has marred the humanity, especially with our long history of mass murder and destruction, it has been able to self-destruct tyranny. So how would this be any different?

Though I'm always suspicious of the power elites trying to create a one-world government, I know it'll fall apart. Egos. Factions. Selfishness. Corruption. Stupidity. The list is endless on why all forms of tyranny have an expiration date. God, who is the Only True Ruler over all, always has a way to destroy and sabotage all forms of evil, including a possible AI tyranny. It may come after a hard lesson for our stupidity. But God, King Jesus, always has a way to ensure that His will is done.

Let's play the not so worst case scenario

Now let's say AI takes over the digital world completely, including all jobs tech. Well...AI's reign won't last. If we abandon the digital world and go back to just living life in the physical world, especially without using anything high-tech, AI will run into a dead end and collapse completely. Chances are we wouldn't be aware of it because we would be doing what humanity has done for most of its history–engaging with each other and the rest of Creation in the real world.

Technical writers would probably exist in some fashion. We would go back to writing instructions and other technical documentation in print. Printing presses will still be here like they've been way before the digital world ever existed. If the digital world ever died, print would just go on. Wouldn't mind using a manual typewriter again if I had to.

The only way is for Artificial Intelligence to thrive and evolve is to have constant interaction with us. It needs our brains and information to think and form its thoughts and actions. AI depends on us, we don't depend on AI.

Those with Little Scruples

What about those who are immoral and want to use AI to impose some kind totalitarian control over others? That's a valid concern. We need to guard against those who wish to do so, speak out against them, and hold them accountable, whether it's governments or their corporate enablers. We must do everything possible to prevent this possible nightmare. But if it does happen, I'm optimistic that this tyranny, as all others before it, will self-destruct. I know Who's the True Sovereign and He'll bring it down. But let's bring this post back to documentation.

Folly on Display

What about companies that have no scruples by replacing technical writers with AI to write their documentation? Well, good luck. 

If we think the overall state of documentation is bad now, wait until Artificial Intelligence completely writes this without anyone checking the content. With confusing or unhelpful information in documentation, companies without scruples will run themselves into the ground. It'll be similar to what the Apostle Paul said to Timothy on the outcome of those who opposed Christ in the last days of their time. I love what Paul says to here:

"But they will proceed no further. For their folly will be evident to all men, as theirs also came to be." – 2 Timothy 3:9 World English Bible

This same kind of folly will be on display for others to see if companies are unscrupulous with using AI to completely create documentation.

Their Lack of Scruples May Create New Fields

Even if these companies succeed by having AI create all documentation, technical writing will morph into something new because of it. Their lack of scruples might lead to the creation of an abundance of new fields. Their outcome in their race for the bottom line will be similar to what happened to Joseph and his family. Look at what said to his brothers in Genesis 50:19-20:

"Joseph said to them, “Don’t be afraid, for am I in the place of God? As for you, you meant evil against me, but God meant it for good, to save many people alive, as is happening today." – Genesis 50:19-20 World English Bible

So rather look at what companies might do with dread, let's look at their stupidity as a way to open up new avenues (and revenues) for us technical writers. Trust me. I don't like it if companies are willing to do this and it'll probably hurt. But I'm not going give these companies any more power than they deserve. I'll choose to adapt and change if this happens.

Possible Counter-Strategy

Now if it turns into a battle between human written documentation versus AI written, we can always come up with a labelling scheme to show the difference. I'm thinking along the lines of what the Organic and Non-GMO movements do with foods. We can put the label and let our audiences decide which quality of documentation is better. This might be good idea for other content creators, writers, and artists out there. But I think it's something we may need to think about this if it becomes a battle between human created material and AI driven content.

AI is a Powerful Tool but Ultimately Powerless

Artificial Intelligence has no power unless you give over it. Even if technical writing dies, I'll pivot and do something else. I trust God to provide because He rules over everything anyway. I may have had a long career in technical writing but it's not my life. I'm okay with whatever comes. In the meantime, I'll keep doing what I've been doing unless God says otherwise.  God didn't call us to live in fear. See what the Apostle Paul to Timothy here:

"For God hath not given us the spirit of fear; but of power, and of love, and of a sound mind." – 2 Timothy 1:7 King James Version

AI doesn't scare me regardless how powerful it gets. So don't be afraid of it either. Take it on and keep on writing.

Freedom in Obscurity

When I was a kid, my dad said something insightful while we're driving somewhere. He said it must be hard to be a famous actor or singer, like Elvis, because you can't go out in public just to get a hamburger. 

I didn't fully appreciate what he said until later in life. When I first set out to be a writer, I wanted to make a name for myself. But God had other plans. He has used technical writing to humble me. I hated this field at first because I wouldn't get a byline. But I've come to embrace this as a freedom. The freedom of obscurity.

Being famous is like a jail on all levels. The following isn't exhaustive but here are few reasons why I think fame is a trap:

• Too much pressure to perform
• Have to constantly care what others think
• Your life is utterly scrutinized
• You can lose yourself in the process
• You can get a big head
• You can forget why you love what you do
• Never enough

Too much pressure to perform 

Let's start with the too much pressure to perform. You have to constantly perform a certain expectation or exceed it to remain in the spotlight. If you don't, then the spotlight can fade away. Yikes!

Constantly care what others think 

Since someone gains a huge following, there's that constant reminder that you must care what others think. You have to match the persona that you built up in others' minds. You have to conform to your fans, agents, producers, sponsors, or whoever is involved in dictating your fame. 

Now there are some who are famous who say they don't care what others think. If that's true, then good. But when many say this, do they actually mean it? If they make their fans and others angry enough, they can lose their fame. Is that something they're willing to do?

Your life is utterly scrutinized 

When you're famous, your privacy goes out the window regardless what you do. Anything from how your parent your children to what you eat will get questioned or criticized. Who wants this constant nitpicking? How would the critics like it if the same standard were against them? Jesus's words are ever-poignant on this.  But it doesn't matter whether this is right. The fact remains that when you're famous are constantly scrutinized and practically dehumanized. This isn't just in the negative sense. You can be dehumanized if think that you're greatest thing since sliced bread. Your fame can turn you in an object to idolize. This leads to my next point.

Losing yourself in the process

With the constant pressures of pleasing others, you can lose yourself in the process. Rather than being yourself, you have to be the thing that others expect you to be. You may have the fame but you're no different than a puppet who performs by the whim of a marionette.  Jars of Clay have had something to say about that.

Getting a big head

This is an easy side-effect of becoming famous. The more famous you become, the easier it is to get a big head. You think you are best, baddest, biggest thing of all. But be careful! The Proverbs speak on what happens to those who are prideful. Besides, your fame wasn't completely self-made. You are at the beck and call of those who lifted up and keep you there. Getting a big head has a price.

Forgetting why you do what you love

Another thing that has falls by the wayside with being famous is forgetting why you set out to do what you love. You're more interesting in conforming the mold you've been placed in than remembering your first love about the thing you did in the first place. You may say platitudes to your original mission but is that still true? Or are you interesting just getting more money and fame?

Never Enough

This should be obvious to those seek fame but I don't think it is who are famous. It might be. But being famous will never be enough. There will be someone else who try to take the spotlight. If not, you must constantly perform, as I said earlier, to stay in the spotlight.

Grateful to be in obscurity

I'm not saying fame in itself is bad. But the pitfalls aren't worth it to me. But if you're famous, then great. Stay humble and seek the Lord is all I can tell you. 

I thank God that he put me in technical writing. Obscurity is built-into the career. I'm free to speak and write without worrying too much what others have to say. My goal is to make sure that I document things accurately and in a way others can easily understand.

I'm also grateful that my novel wasn't a bestseller. I can imagine in that. I prefer to be an obscure writer. I would love to write more novels but that's not my focus. My focus isn't even on this blog. My focus is on technical writing unless God calls me to do something. 

Finally, I'm grateful that this blog doesn't get much traffic because I'm free to write anything I want here. What's the worse that happens? You don't like what I wrote. That's fine. You don't have to. You can close the page and move on. 

I'm truly grateful that I live in the freedom of obscurity.

Writing for Validation? No!

There are many reasons to write. But there are reasons not to write. Validation is one.

If you're writing to seek approval, then you're going to be disappointed. While it's crucial for writers, especially those of us who are technical writers, to build bridges with the audience you're trying to reach, you're not going to find validation from them. 

The audience doesn't care who you are or what you write. Ultimately, they're just looking for information and content they want and they move on once they get it. If they return, it's because they're looking for what they want, not you. Now, some may counter me and say they like certain writers. Is it the writers themselves they seek, unless you're some nut job stalker, or stuff they write? You know the answer to this question.

If you're looking for approval with your company, good luck with that too. You might get some unsolicited advice if you're constantly asking Subject Matter Experts (SMEs) whether your writing is any good or your documentation has any value. They'll let you know if they're not happy.

Taking constructive criticism is one thing. We need it to improve as writers. Writing is an ongoing process. We only get better by doing it constantly and humbly taking feedback. Heck! You can even send surveys to your audience and the SMEs to see how you can improve documentation. After all, documentation is about serving your audience. But seeking validation is another. It's an unhealthy extreme. Validation is a phantom prison!

You're afraid of what others think and you ruminate about the possible criticism or some half-cocked comment from someone. So, you try to appease them and you lose your voice in the process. But in reality, they're not even thinking about you at all.

The fatal problem with seeking validation is it makes you the center of the universe.  But guess what, you're not the center. 

Seeking validation is in the same vein as comparing yourself to others, but it takes it a step further into narcissism. What one really wants is accolades and praise? What someone who seeks validation wants is an echo chamber. Let's be honest. Do any of us go around seeking to find criticism, even if it's constructive? No! We prefer to do things our way. I'm not saying that's right. I'm just saying that's what we tend to do.

So why seek validation for your existence as a writer, particularly a technical writer. Let's keep our heads down and power through to great documentation. Leave the rest up to God. Seeking validation is a big waste of time and energy. Don't do it! Be humble yet confident in your abilities. But if you're writing only because you want the approval of others and want people to extol you, then maybe you shouldn't write at all.

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

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?

Salmagundi within Documentation

According to Meriam Webster, Salmagundi is:

1. A salad plate of chopped meats, anchovies, eggs, and vegetables arranged in rows for contrast and dressed with a salad dressing

2. a heterogeneous mixture : POTPOURRI

Salmagundi is also a name of various publications throughout the years. But I don't want to turn this post into a salmagundi. So, I digress.

While salmagundi might be a tasty dish, it doesn't taste good in documentation. Unfortunately, salmagundis are a common problem within documentation. Salmagundis obscure, confuse, and can lose the reader. They're bad, especially when your reader needs to learn critical information. What do I mean by salmagundis in documentation?

It's when documentation goes onto over-technical tangents or tries to cram too much information into one document, especially if it's irrelevant information. So much so, you end up with a technical word salad. But sadly, this is the state of much technical documentation out there. I can't count how many times I've seen this be the case. So how do we avoid creating technical documentation salmagundi? Here are some tips. They're not exhaustive but they should help.

Know Your Audience

This is the key to start your documentation. If you know your audience, you'll know how much information to include, how much to leave out, and what kind of information you need to write.

Know What You're Documenting in 1 Sentence

If you understand what you're documenting, this makes a big difference. If you can sum up what you're documenting in one sentence, you'll know where to go. For example, if I said "I'm writing about how to make coffee," then this will direct what steps or information that I need to write. 

Focus the Documentation

If you focus on what you're documenting, this reduces the chances of it becoming a technical word salad. You'll know what points you want to write about. For example, if I were to create a user manual on how to run coffee maker, I'm only going to show you on how to run the coffee maker. I'll include some troubleshooting tips. I might even include the suggested amount of coffee for each scoop to put into a filter. But nothing beyond that. If we don't focus our documentation, we'll get lost in our writing. And that won't be helpful to anyone.

Leave Out Irrelevant Information

This is an extension to the previous point. But it's worth noting. When you write a document, you need to leave out the irrelevant information. You can overwrite by including every tidbit of information about something. But you risk confusing your readers, especially if the information is irrelevant. 

Back to the coffee maker example, I'm not going to mention how the coffee maker was made or what kind of roast would be best. Or even, how to store your coffee. All these points are irrelevant on how to use the machine. You only need to know how to run the coffee maker. Anything else confuses audience or distract from you need to know. 

There will never be an end to the information you can bring up. But a lot of it is neither relevant nor helpful to your reader. So if strays from the point of the document, leave it out! Once you finish writing the document, look through it again and cut what irrelevant information that remains.

I love what Mark Twain once said about books. And I believe it applies to documentation. Twain said:

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

Consider Multiple Documents

Now there are times when you need to cover a lot of information. Just listing steps to your reader might not give them the whole picture about a product or service. If you run into this situation, then consider writing multiple documents. 

So if someone goes through the steps to run a coffee maker but needs to know to grind coffee beans and store them, then write two other documents. One is how to grind the coffee beans. The other would be best practices to store the coffee beans. Breaking down in smaller, more focused chucks goes a long way.

Especially now, when a lot of documentation is digital. You can write short documents and hyperlink them to each other. So, if a reader needs to find further information, they can go to the document that's relevant to them instead of thumbing or scrolling through one big document to find it. 

When I first started technical writing, we would jam as much information as we could into one document. We would sometimes break it into a couple of volumes. But we were doing this because of printing costs. But now, creating digital documents is a fraction of that cost. Sometimes, you can create digital documentation for free. So, there's no excuse to jam everything into one huge document, especially if you only write digital documents. So break up the documentation into easily, digestible information. 

These tips should help keep the documentation focused like a themed dish instead of a salmagundi. It won't be perfect because no documentation is. But, it should go a long way. Keep on writing.

Perseverance Instead

I remember a martial artist, who is a master of his art, once told his students that he didn't get to his belt rank because he was any good. He shook his head as he spoke to them. No, rather he got to his level because he didn't give up. He encouraged his students to do the same.

I appreciate those who tell others to perservere. This is the only way to get better at anything, even with technical writing.

 

I didn't get to the level of where I'm at as a technical writer because I'm any good. Far from it. I don't think I'm a good writer. I didn't get to it because I'm smart. I don't think I'm that intelligent. I only got to my level of technical writing because God kept providing opportunity after opportunity and I preserved, even when I didn't know what my next gig was. 

Anyone can become a technical writer but not everyone remains one. Anyone can persevere when something's easy. But that's not true perseverance. It only becomes true perseverance when it's hard.

Technical writing can be difficult, gruelling, and thankless. It feels like you can't write anything when your documentation gets picked apart. But before you slump into despair and give up, remember these difficulties can help you grow. You can't get better as a technical writer unless you know what to improve from. That's why feedback is important. Improving your technical writing only comes through mistake after mistake. You just have to persevere. Only this road of perseverance can help you become a stronger writer.  Once you get to the other side of the troubles, you'll see how they helped you grow until the next storm. Each storm is worth going through, if you want to get better.

But before you rush into a storm, count the cost. Is technical writing worth it? It can be demoralizing at times. But it can also be rewarding. If you feel technical writing is a worthy trade, then keep going no matter what. Otherwise, look for something else instead.

I find technical writing a worthy calling. I love to write and structure information. I also love to help those in need. For me, technical writer combines those two together. 

Until God calls me to do something else, I'll keep persevering. And if you're a technical writer, who's on the ropes, don't give up either. You're not alone. I've been there and it's eventual that I'll end up on the ropes again. We all end up there. It won't be the first time nor the last time till we hang up our pens, pads, and keyboards. If you don't think you can hang on, then ask God to help you persevere. He will help you get through. He has helped and continues to do so. Don't give up.

Collaborate, Collaborate, Collaborate

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

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

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

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

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

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

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

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

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

Benefits of technical writing

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

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

Improves your writing 

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

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

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

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

Reduces or eliminates writer's block

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

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

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

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

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

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

Organizes your thoughts, even for your creative side

Technical writing can help you organize how you write information. 

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

1. Remove the car out from the package.

2. Place the car on a smooth surface.

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

4. Let go of the car. 

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

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

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

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

Better see big picture and details

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

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

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

Focuses your writing 

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

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

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

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

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

Always learning something new

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

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

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

Highs and lows but still good

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

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

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

Hard at times

Throughout my journey as a technical writer, I've encountered other technical writers who fall under a few camps. The following is not an exhaustive list. One camp is they're passionate about technology or the industry they're writing about. Another camp is they use technical writing as a springboard for career advancement. A third camp is it's just a job for them. Finally, they're ones who are passionate about writing. 

Typically, I've encountered technical writers that are in the first camp or seem to be in this one. That's great for them. But I don't fall under the first camp. It's hard at times to be passionate about technology or industries. These subjects are interesting but they get old eventually. Also, it just comes back to making money, regardless they spin it. Now, there's nothing wrong with making money. I like to make money too. And I believe in free-enterprise, if it still exist and if it's done by honest and just means. But life is more than just making money. 

I don't care to use technical writing as a springboard. I'm content as a technical writer. So when corporate well-to-dos ask me where do you see yourself in blah, blah, blah, it's like I'm talking with someone from another planet. (Now, I wouldn't mind speaking with extraterrestrials.) Why would leave creating documentation for some middle management position? No thanks. Not a good trade for me.

Technical writing isn't just a job for me either. It's a craft. But it's also not my life. God and my family are. So, this leads me to the last camp, which seems to be the smallest based on my travels. But I don't like to write for writing's sake. So, I don't completely fit this camp either. I love to write with a purpose. If there's no clear purpose, then I don't want to spend the energy to write. I don't find it a good use of my time.

So, if I'm not passionate about technology or industry, "career advancement", or for writing's sake, then why I do it? I'm a technical writer for three reasons. One, I like to write. Two, I like to help others.  Three, I like to find a good way to provide for a family. As far as I know, technical writing is the best way to combine these three passions together. 

Whether we should be inundated with technology or ruled by industries is another conversation that I may address someday in this blog. But for now, I'm just here to help guide others through the informational and technological labyrinths. My desire to write and help others is what drives me to understand these subjects, so I can write about them well. And my desire to provide for my family fuels my technical writing journey to continue, even though God is the One who really provides. I'm just here to follow His lead on the means, even though sadly I've gotten in His way to do so many times.

So when others ask me about what tools to do documentation or get into debates which one is better, I don't care. I can tell you pros and cons of tools I've used, but it's not a hill for me fight and die on. I will use whatever tools I have available to create good documents. 

I care more about the bigger picture: Creating clear and accurate documents for the intended audience. I'm more interested in what makes good documentation than certain toolsets. I find too many technical writers or higher ups get hung up on the latter rather than the former. What is the point of tools if documentation is confusing, wrong, or overwhelming? Let's stick to good documentation principles and rest will follow.

Maybe I'm in the wrong field. Maybe technical writing is really for technophiles and corporatocrats. Maybe I'm just an anomaly, but that's thinking too highly of myself. Maybe I should look elsewhere. If there were a better place for me, then I'll go there. Maybe if I could just speak better and verbally explain how something work, I would ditch the writing thing. Writing is great but also very painful and draining. But this kind of thinking like this is fruitless and wasteful. For now, unless God makes it clear, I'll stay here in this technical writing game.

God gave me a gift and I will use it to glorify Him by writing clear, accurate, and easy-to-follow information so others can understand. I spent far beyond enough years doubting whether God gave me this gift and skill, so I can hone it. I'll go with it till I can go on no more. In the meantime, I'll keep on writing in the tech world.

 

Yay or Nay

This is very clear and well thought out documentation. Bravo! This is very confusing and lacking. It's needs to be better. 

These comments that I've received from others as a technical writer. People have said positive things about my writing. Others have said negative things. And there are others who have been in between.

A big part of this game of technical writing is yay or nay! Thumbs up. Thumbs down. (You might get meh or sideways thumbs.) It's a brutal game at times. But that's just the way it is. But why?

Based on my years of doing this, it comes to this:  Someone's feelings about how you wrote the information is subjective. The information about  might be objective truth. But how you write about it and what someone thinks is not. So, no two writers are going to document a subject the same way. No two editors or Subject Matter Experts (SMEs) will react the same way to your writing. No two people within your intended audience will feel the same way either. You can't just please everyone. It's really a game of yay or nay. And the sooner you realize that, the better off you'll be.

But if we want to keep finding work, we can't have a totally blase attitude either. So what can we do?

All we can do is this: Do your best to understand the subject at hand.  Do your best to understand your audience. Do your best to write the information. Beyond that, there's nothing we can do.

People can be fickle, contradictory, and unreliable in their opinions about what we write. It's really yay or nay. (Meh, if you want to break the monotony.) And that's just something we have to deal with. We just have to shrug and do our best. And if there are ways we can improve, even better. Beyond that, it's whatever. So knowing this, there's one thing we shouldn't do: Do not tie your value as a writer or as a person to what others think of you. Doing this, might make you neurotic. It's not worth it. Why tie your identity to another's whim that's flimsy than paper.

If you want to break the part of the technical writing game that's yay or nay, then don't tie your values to others, especially to those you work for. They are ultimate yay or nayers, sometimes in one breath.

If you're willing to accept this, and you don't have to agree with me, the way to break the yay or nay is tie your identity to God. He's not flimsy, like the corporate types, He's a rock, which you can firmly stand on. Unlike the corporate types, He really cares for you. He doesn't care how you write. He just simply cares and love you because He made you. For me, staying grounded in God no matter what is making all the difference. And if you accepted that, then maybe you can accept this:

Therefore, whether you eat or drink, or whatever you do, do all to the glory of God. -- I Corinthians 10:31 NKJV

The Moment

As a technical writer, you might have this epiphany too: What you work on isn't yours. 

Sad to say no matter how much or how long you labored away, the documentation you create isn't yours. It belongs to the company. 

For some, this might not be a problem. For others, such as myself, it's harder to accept. But it's a fact that I had to accept. I may have worked on documents from their inceptions, but I don't get to own the fruits of my labor. I'm really creating someone else's product. 

I have had to detach myself from documentation, and it's been a painful process doing so. Why? It's because I like to create and write. But what I'm writing and creating isn't mine. Even if they say you own the documentation, the obvious fact is otherwise.

So what do you do with this? When the higher ups want to change the direction of documentation or scrap them all together, we just have to let them. You can give your thoughts on this, if you feel there are better ways to do this. But, we ultimately have to let go. Fighting is a waste of time and energy, because it's not ours to fight for. And when the time comes when you leave or they let you go, it makes easier to leave behind the documentation. But knowing this truth shouldn't give us a pass to create subpar documents.

Work hard and create quality products but don't get too attached. Steward and manage these documents with excellence. But we're servants, maybe keepers, not owners of the documentation. So keep that in mind. And it's a balance we need to maintain, if we want a healthy outlook on documentation.

Maybe someday I'll own a technical document because it'll be tied to a product I created independently. I could imaging writing the script for a JRPG (something like Final Fantasy comes to mind) or the instructions on how to play it. But I'm not sure if creating products is my calling. Maybe an exception is publishing another book but that's yet to be determined. But who knows. Life, especially the future, can be a strange thing.

But, if we were honest with ourselves, we truly don't own anything. The true and rightful owner of all is God. And we should really surround our lives and efforts around God. The sooner one accepts that, the better. I have to keep learning this truth, even when it hurts.

"The earth is Yahweh’s, with its fullness; the world, and those who dwell in it." -- Psalms 24:1 WEB.

Word is here to stay, at least for now

Whether we like it or hate it, Microsoft Word is here to stay. (At least, for the foreseeable future.) After all these years, I've realized beyond doing basic stuff and slightly beyond that, I would avoid using Word when creating very intricate technical documents. But, I don't let that be the case anymore.

Long ago, when I was younger and stupidly dogmatic, I got into a heated argument at a meeting because someone suggested we use Word instead of Adobe FrameMaker for our manuals. Mind you, the documents were an average of hundreds or thousands pages long. I rebuffed the guy who suggested it and said in an exasperated manner Word would screw up our documents because of the sheer size and everywhere else with it. I dogmatically told Adobe FrameMaker was the tool powerful enough to handle this. 

Oh, silly, silly me. Where is FrameMaker now? It still exists but it's not as widespread as it once was in technical writing circles. The claims I made about Word no longer hold water because it continues to evolve. Word can handle immense docs. I have done them in Word, cross-references and all. (My book was done in Word eventually. I first wrote it in a flavor of Markdown.)

If you want to see how intricate Word can get, try opening the Developer tab. I barely scratched the surface with this function, but I can see how robust this is.

I'm not slighting FrameMaker. I still think it's a great tool, especially with complex technical documents. I used it for many years. But who wants to use a tool that's very overwhelming at first and not very accessible to the average user. (Yes, this can include technical writers.)

Word allows for more collaboration with SMEs and others with comments. Word has an easier learning curve. It's those like me who overthink on how to use it. 

And regarding sheer size of documents, I could have avocating breaking them in smaller documents. Or, if the audience didn't need to know more detailed technical information, I could avocated in removing big swaths of material to what was important to know. Looking back, I would have things differently. But it's not good perserverate over things. I did what I thought was best at the time. The important thing is learning from it and move on to make better choices.

I've learned to appreciate Word. Slowly but surely, I feel more at ease creating documentation in it. What's the secret?

The key is to work with the tool, not against it. We need to accept Word for what it is and not try make it something that's not.

I have seen technical writer conferences advocating for other more highfalutin tools. Something the average person isn't to use. Nor is it cost effective to purchase something like this. To me, it's seems like they're avoiding this simple tool. But what do I know? I'm just some schlub who types words on a screen. 

Now, Word falls short. But so do all other tools on this planet. You just have to decide what's most accessible to use. Word happens to one of the most ubiquitous. So, make the most of it. Why fight against something that's easily available?

But, tools shouldn't make up your technical writing prowess. It should be skills. So, if you only had a stick to write with and the earth is your canvas to create a document, then it shouldn't be a problem. 

Ask Two Questions, Maybe Three

When you create a document, you need to ask two, maybe three questions. But at least, you need to ask two. So what these questions? They are:

- What is this thing I'm writing about?

- Who is the audience I'm writing for?

- What kind of document am I writing?

Why does it seem I waffle between two or three initial questions? Well, you may not need to ask the third question because it may come up naturally in your conversations with the SME(s).  Only ask the last question if you need to. Otherwise, the SME(s) may lose confidence in your ability as a technical writer.

But the first two questions, you should definitely ask when creating documents, especially if you're in a new setting. So why these two questions? Well, these two questions will help set the direction of your documentation. 

If you know what you're writing about and who you're writing for, it'll help you know what kind information to write in your document. Let's say you're writing a user guide on how to use a software for storing recipes and your audience are home cooks and chefs, you're not going explain the technical inner workings of the application. You're just going to show them step-by-step how to enter and save their recipes. That's it. 

When we approach documentation, we should take Mark Twain's advice when writing good stories. He said:

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

So, let's focus on what to write and chisel out the rest. Our audience deserves it.

Microcontent--Make Your Point Quick

"Brevity is the soul of wit." -- William Shakespeare

This proverb rings true for good writing, especially microcontent.  

Microcontent is using few words to present valuable information to your audience. Anything from a tagline to a tooltip is microcontent. Microcontent is supposed to catch a reader when they're skimming. It works! I get caught when I see keywords that catch my eye. And if you're honest, it catches yours too.

In our time, microcontent is what draws your readers in. Short. Sweet. Effective. That's microcontent. To find out more, check out here and here.