Search This Blog

Thursday, November 17, 2022

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.


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.

Wednesday, September 14, 2022

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.

 

Saturday, August 27, 2022

Can't Write Everything and That's Okay

One of the main reasons why I chose the writing craft because the possibilities seem endless. But for a hundred ideas, I will commit one, two, or maybe three to pen. And only one of those ideas, I'll see it through and publish, while the other sits as a draft until I decide its fate. Why do this? Why not write everything? I can't. I won't. And I'm okay with that. 

Too Much is Just That

Like we shouldn't say everything that's in your head or take a picture of every experience, unfortunately in our time, too many do so, we shouldn't write everything that comes to mind. We shouldn't. But, too many do so.

The problem in our day isn't the lack of content but the overabundance of it. A lot of stuff out there is crap or worse. So rather than getting a lot of good content, we get a lot that's empty, flaky, or downright fake. (The last point I'm referring to things that should be non-fiction but turn out to be fantasy). 

This kind of content is like over-processed food to the mind. 

Like those who suffer from health problems from over-processed food, our minds, emotions, and souls suffer from over-processed content.

How does reading another article on something trival help enrich you or someone else?  Or is it just something that fills time, while you're scrolling through your phone or flipping through a magazine waiting? How about reading content that's says it's true but turns out to be based on half-truths or lies? How does that help?

It's About Prudence

When you write, I believe prudence is key. 
If you're working on a project that's sunk in the muck and mire because you're neither equipped to handle or there's absolutely no direction, you could be wasting your time and energy. You're defeating the purpose as a writer by not focusing on projects you can do better with less effort.  (Trudging through the slog of writing is okay, but to be stuck completely and it gets worse the more you try is not.)

Dose of Realism

While as a writer, you should strive to grow and expand your abilities and horizons, we also need to be realistic and humble. We need to be aware of our limitations.

Before we commit to writing something, we need to ourselves some questions: 

- Do I have the ability or time to do this?

- Do I really know about the subject I want to write about?

- Is this helpful to others?

- Is this a good use of my time?

- Am I filling a need?

- Is there someone else who has already done a great job or can do a better job than me? 

- Is this about my ego?

The world is big enough for all kinds of writers. So, why not give others their due and find the area you can write about and excel there.

Writing is a balancing act. If we want to be good at this craft, we need to also learn to discern whether to create something or just defer it off to others. Only you can truly answer where that line is. (But if it's solely about ego, don't write it.)

What about Technical Writing

So, what does this have to do with technical writing? Much in every way.  While we should document everything, especially if the intended audience needs it, there's also over-documentation. 

(As a technical writer, I don't determine what gets written, the organization does. I may give my thoughts on what should happen. But, I don't get a final say.)

Over-documentation can be confusing and overwhelming to your audience. 

Who wants to read through reams or scroll through reams of information to get what you're looking for? I know I don't. 

I believe in documenting every crucial piece of information of a product or service. But if we write about every detail or variable about a product or service, we risk getting the customer lost, where they may miss what's important to understand on how to use something.

For example, let's say you want someone to choose option Y after selecting option X. But then you go on and on about why this choose option Y. Then, the mindset of creating these two options. Who cares! You just tell them "Once you select option X, choose option Y." The other stuff should go in a white paper or some marketing copy. Instructing someone how to do something should be focused on taking someone through the steps till they're done.

In some cases, over-documentation can be condescending and you risk losing the audience you're trying to reaching. You wouldn't tell someone how to turn on a computer if you're telling how to use a certain software. The assumption is they know how to turn a machine. You're simply there to walk them through on how to use the software. If they don't know how to use a computer, then it does no good to explain a particular software.

Look At Design 

If you look at what people in User Experience (UX) do, they strive to create something that's intuitive. The idea is where someone can pick up something and use it right away, so there would be no need to explain how through documentation. 

But, not everyone is at the same level. And that's fine. I believe this is where technical writing can help UX.

If we create products and services that are friendly and easy to use and understand, then we only need to create minimal documentation.  We should document where it counts. And when we do, we should create documentation that's intuitive and easy to follow.

Writing with Focus

If we focus on writing we can do and what's needed, I believe we'll have better and smarter content. Fewer but better content. We can even apply this to writing opportunities. Not all will fit your abilities, so pick the ones you can excel at and go from there.

I know I can't write everything or about everything. And I'm okay with that.


Monday, August 15, 2022

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








Friday, July 22, 2022

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.