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.

Show, Not Tell–Bring Documentation to Life

As you've pursued the writing craft, you may have heard or read the following:

"When you write, show not tell."

This is great advice. Showing rather than telling brings life to your writing. I struggled with this when I first started out. I still struggle at times. But what does it mean to show rather than tell? Let me attempt to give an example:

Tell: Toby went across the rocky, cratered terrain on his rover to get to the city.

Nothing wrong with this sentence. It describes what's Toby is doing. And there's nothing wrong with just telling your readers what's going on. For me, it's simplest approach. But if you do this with every single sentence, your writing might become flat.

Show: "Uoof," Toby cried as he went over a rock. "This is no easy cruise. Whoa!" Toby sharply turned the steering wheel of his rover to the left to avoid falling into a crater. "That was close! Just a few more miles before I get through this rough patch. I see town up ahead."

Here, showing adds dimension to what Toby's doing.  It's more than just writing more sentences and adding dialogue. Far from that. It's about painting an in-depth picture, especially if it helps the story along. 

But with all great pieces of advice, we can take it to an extreme. If we show everything, then we can get an overwritten mess, where you might overwhelm or confuse readers. You might end up with written pictures without any context to link them. Narration is telling a story, regardless how you look at it. Knowing where to show and where to just tell is tough and can only come through practice and time. The key with showing is using it where it better communicates you're trying to say.  

Showing in Technical Documentation 

One of the advantages with technical writing versus other styles is showing versus telling is easier to do. I'll explain how. Rather than crafting a narrative like the example above, you can use screenshots and other examples in certain parts of document. 

If a flowchart or a screenshots succinctly explains a concept or an action better than writing out paragraphs of text, then use the picture. The cliché "a picture is worth a 1000 words" is true in technical writing. 

If you're writing something like API documentation, then showing code examples and call responses will help communicate your point across. I would venture to say with API documentation, code examples and responses are more important than the writing itself. So, showing is crucial. For an example, see one from Square.

I would include hyperlinks in showing rather than telling, if they better showcase what you're trying to say. 

But you don't want to place screenshots, code examples, or hyperlinks just for the sake of doing it. You risk having a bunch of examples without context.  Doing so, might confuse and overwhelm your audiences. You want to place examples in your documentation because they better clarify information you're trying to convey. Knowing where to place visual examples instead of writing is key to good documentation. 

Showing examples through code examples, screenshots, and graphics will help your technical documentation come alive, especially with clarity. Sometimes, your audience might use your examples as a shorthand way to comb through the documentation. So, make your examples count.

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.