Search This Blog

Tuesday, October 11, 2022

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. 

Monday, October 3, 2022

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.