Search This Blog

Showing posts with label Technical Writers. Show all posts
Showing posts with label Technical Writers. Show all posts

Friday, July 11, 2025

Clear Writing is Crucial to Using AI

This post is an addendum to a previous post. Though I'm still not afraid of AI, I've come to terms it will alter the landscape of what we do as technical writers. With the launch of Grok4, despite the controversy that surrounded it, this reaffirms AI isn't a passing fad. Those who think otherwise are living in a fantasy land. Unless there's some grand event that causes technology to cease, there's a mass rejection of AI, or even a bigger innovative leap, it isn't going away. But despite how powerful it is or how it will get, AI is still a tool and it's a tool that we need to master. So how do we do this as technical writers?  We focus on writing clearly. 

If or when we need to use AI to help us create documentation, we'll need to use AI prompts. In those prompts, it will be key to write clear and specific instructions. We can lay this out how we want the documentation to look. Of course, we will still need to writing the content itself or we should. Using AI isn't an excuse for us to shirk our duties as technical writers. If anyone does this, I'm absolutely against it. Documentation will always need human nuance to make it good. So we still need to do the hard work!

One of the nice things about using these AI prompts is that we can constantly refine our creation so it will eventually match what you're looking for. Or, it might even exceed our expectations. Of course, it can become a problem with when you're using a free version of the AI. Waiting another day after you past the message limit to clear isn't always ideal, especially if you need get documentation out for an impending release.

By focusing writing in clear, specific, and concise instructions in these prompts, it drives us back to the heart of the technical writing style. In a weird way, it takes us back to good ole technical writing.

Is it a possibility that AI will eventually make technical writing disappear? Don't know. Only God knows the future. I may have still concerns with AI but it's not going to take over, if we don't let it. What I do know is new opportunities will arise when old ones die. We no longer have milkmen but we do have refrigerator repair technicians. Just keep on writing. If you need to use AI, then make sure your voice and skillset still shines. I think I'm with this topic for now.



Friday, October 25, 2024

Unless it's documentation, I don't do major revisions

That's right! I don't do major revisions once I publish something. Once it's out there, I move on to the next project. The only exception is technical documentation. By nature, technical documentation is fluid because it's contingent on the product or service it documents. So if there's a major update to a software, I would expect major changes to the documentation. Even with minor software updates, depending what's changed, I would expect changes in the documents too.

We technical writers are constantly writing, editing, and revising materials when we're actively working on projects. Some may call it a curse. I call it a blessing because we get further use and hone our craft.

So my rule of no revisions doesn't apply to technical writing or technical documentation. I'm talking about published works outside of this realm. 

Erases Your Growth


When we go back and do a revision of work we've created and published, it erases the growth we've made as writers. (I'm not talking about works that need periodic or regular editions. In those cases, you would need revisions to keep your material relevant or accurate.)

My earlier work isn't good. So what! While I still don't believe I'm a good writer, I've seen continual growth since I dedicated myself to the craft.

Growing Since My Novel


When I published my novel The Unlikely Messenger in 2019, it was a feat. I was in knots whether it was good but I pulled the trigger to get it out. It was sitting somewhere tucked away for years. My thinking was if I wrote something and I'm okay with it, then why leave it unpunished?

I'd probably cringe if I looked at my novel again. It's been a while. I know I've changed since then, especially in matters of eschatology. I've also tried have a more consistent Christian worldview since then, though I still have a long way to go.

Would I write a dystopian novel again? No! While tyranny, evil, and injustice is rampant, dystopian societies don't last for the long haul. They either end in overthrows or implosions. History shows they always go into their dustbins where they belong. So if the powers that be managed to create a one world government, it would be destined to fall apart. Even if God doesn't intervene, people's egos, especially those in power, will make it implode or nations would break away anyway after getting tired being told what to do.

But would I go back and make revisions to my novel? No! For if I did that, it would no longer be the story that I wrote. I'm okay with the follies, blind spots, and probably bad writing that's in there. It's a benchmark for me to know where to go from here.

I Let Blog Posts Stand, Well Mostly


I don't even go back and revise my blog posts either. If I went back to say it better, then it would no longer be the posts that I've made. The only exceptions would be spelling and grammar errors or a factual error if I notice. Besides that, the posts stand.

Cancel Culture Nullifies Progress


The cancel culture is beyond ridiculous because it doesn't allows us to be humans. Are there stupid or evil things we all may have said or done? Yes! No one is above this folly. Let's discuss them honestly. Let's own up to them. But to cancel people for what they said or written years ago even they don't believe those things anymore, and even now repudiate those previous beliefs, negates their growth. Those past errors and evils are there for us to learn from. (I'm not talking about people that are still doing and saying stupid and evil things.) If we erase or cancel them, then we're more apt to repeat the same evils or follies because we'll no context or history to move forward from. 

Be Careful about Embracing this Mentality


Be careful about embracing the cancel culture. If we're going to be consistent with embracing the cancel culture, we have to erase everything, including ourselves. As Jesus said, be careful about the measure we use for it will be used against you.

Any writer worth their salt should understand the danger of the cancel culture mentality. This mentality will destroy vigor in all writing, including technical writing. I'm glad people have pushed back on it. I hope this absurdity goes into its dustbin. I digress.

Don't Erase Your Mistakes


The easiest way to hit a plateau where your writing becomes sterile is where you're obsessed with erasing imperfections. How will you know that you've grown and progress as a writer, if you can't embrace your earlier mistakes? Accept that you made them. Learn from them and move on. 

Be Human and Understand the Journey


We as writers must be at peace with what we put out, even if it makes us cringe. I still cringe at earlier technical documentation I've written, even if it was a short time before.

Seeing the progress you've made as a writer is far better and more rewarding than trying to have everything look and sound "perfect."  That sounds boring and machine-like. Be human. Understand we're all on a journey as writers. 

Thursday, March 30, 2023

Be thorough, not Pedantic

As technical writers, we must be thorough when we create or edit documentation. If we're not, then we might present shoddy, confusing, murky, or incomplete information to our audience. But being thorough doesn't mean you should be pedantic. 

Pedantism is annoying at best and destroys relationships at worst. It's unnecessary, short sided, and stupid.

But what's the difference between being thorough versus being pedantic? For us, being thorough is carefully making sure the documentation is clear and helpful for our audience. Or when you're dealing with SMEs, you ask good or the right questions to get the information you need. But being pedantic is pointing out, or if we're being honest with ourselves, picking on small details that don't matter. 

Does it compromise the clarity of the documentation? If not, let it go. But if one wants to insist these details are important to point out, then think carefully and honestly. Are they important? Seriously, are they?

Or, if there's a small error or limitation and you can safely assume (it's okay to assume sometimes) most people are going to figure it out, then let it go. 

How about speaking with others? Are you going to point out to small inaccuracies in their word choices because it's not to your liking?

One of the worse forms of pedantism to me is when someone corrects someone's grammar or pronouncing when they speak. Why?!  Did they ask for help speaking? What are you doing other than showing how smart you are and showing how stupid you think someone is? Are you that thin skinned that you can't possibly hear an imperfection? If you understand someone's point clearly, then why do that. All it does is sour relationships. If you want to be a successful technical writer, it goes beyond great writing, grammar, and editing skills. It's also about building great relationships. Without it, you might have nothing to document.

Don't think I'm okay with bad grammar. I just save correcting and improving the grammar for documentation. And even then, the grammar rules we uphold aren't as ironclad as you think. (While these rules give structure and meaning to any language, they aren't infallible. Sometimes, these grammar rules are fake.) Don't believe me. Look it up. 

If given the choice, I rather take a clear sentence that they may not be perfect grammatically, than one that's "grammatically" correct yet clunky in its explanation.

Guess what? No matter what you do, no documentation is perfect. No tool is perfect. No one is perfect. Nothing except for God is perfect. It's an exercise in futility if you strive for that. Instead, strive for clarity, technical accuracy, and good document design the best you can. The rest will take care of itself. If you need to make improvements, then so be it. 

Besides, you wouldn't want perfection because there would no longer be any innovation, whether on the subject you're documenting or documentation itself. Think where that ends up, if there's nothing to improve because of perfection.

Pedantics, like legalists, focus on the minute details but not the big picture. It reminds me what Jesus said when He rightly rebuked the Pharisees for their pedantry. Check it out.  

Also, pedantics may like to impart their "wisdom" on others. But they don't like when someone else does it to them. If a pedantic person is honest, then they don't like that. It reminds me of what Jesus said here about the measure in judging people. Check out what He says here. If anyone wants to be pedantic, then they'd better be prepared for other pedantics to correct them. 

If not, why carry the weight of pedantism around? It's not just a burden others, it's also a burden on yourself. Dump pedantism into the metaphorical ocean. (Don't actually dump anything into the ocean. Seriously. Don't. Let's keep it clean, if we can.) Free yourself from it. If you don't, it can hinder you from growing as a technical writer.

Now, it would be hypocritical of me to lance pedantism from a high holy horse without admitting my own faults. I've been guilty of having some pedantic tendencies in the past. Mine was trying to absolutely uphold style guide conventions, but I didn't take context into account.  While I still think style guide rules and convention are great, they're not absolute. I'll also still uphold style guide conventions, but if a sentence sounds clearer and more natural and it "breaks" with convention, then I will choose this sentence over some arbitrary rule. My focus is on the big picture: Creating clear and helpful documentation for the intended audience.

By trying to get away from these tendencies, it's helping me to continue to grow as a technical writer. I'm able to work with liberty and confidence. And my relationships with SMEs have also improved over the years.

Life is too short to be pedantic. Focus on the big picture. Is the documentation clear? Is it helpful?  Writing in active voice goes a long way with this. Is it for the intended audience? Building genuine and good relationships with SMEs will help you understand your audience. Do it with a smile and laugh.

Don't let the minutest of details distract you from that, especially the ones that don't matter in the big picture. When it comes to pedantism, that adage "the devil is in the details" applies. So, let's prevent the devilish details from winning out.

Be thorough, not pedantic.

Thursday, February 4, 2021

SUI, SUI

SUI. SUI. I don't want to get su-ed. Yeah. Yeah. Yeah. Yeah. Yeah.

SUI is not something that just rhymes with a name in a popular song. It also rhymes with GUI. 

SUI (Simplified User Interface) is something we technical writers should take note and embrace. SUI is a graphical means in upholding our mission: Using simple and clear means to introduce our audience to complex and intricate topics. 

SUI goes hand in hand with our craft. It's more than just a style of an user interface. There are principles behind it, which is why it caught my attention. SUI upholds the spirit of technical writing itself.

If you want to find out basic information about SUI and why it's useful, then check this out.