Read to Write

You may heard the saying along these lines:

If you want to be a writer, then write.

The overused cliché in life is when you hear people talking about writing such and such all the time but don't put down a single word on paper or type one on a screen. You won't ever be a writer unless you write. (I'm not talking about those who have finished unpublished work. They did the hard first step. They are writers in my book. There are numerous factors why this happens. But I am not going to address that here.)

While I wholeheartedly agree with this saying above, there's something else you need to do before you become a writer. You must read before you can write. 

As a writer, it's important you become an avid reader. (Audiobooks count too by the way.) This not only stimulates your brain, you can also learn how other writers write. As I mentioned years ago, I learned a lot from June Casagrande's book, as well as Professor Strunk and E.B. White,  William Zinsser, Philip K. Dick, Tolkien, and even the Bible.

It was a privilege to have learned from them and other writers. They helped shape my writing style as a technical writer. And I hope others can learn from me as well. 

Reading is essential to become a writer, including becoming a technical writer. If you want to get into technical writing, you should read technical books or publications themselves to see how they write. (And if there's a industry you want to get into, you should read about it.) When I dove into my first serious foray with API documentation, I read an e-book about this from Zapier to get an understanding. 

You can also read link to it in blog form. Recommend it if you want to get into API writing.

But reading other writers to become one shouldn't simply be about gaining knowledge or emulating someone else's style. When you read like this, it should accomplish two things:

1. See how you could have written it better. (The only big exception is the Bible because that is God's Word. You read that to learn who God is, what God says, and how He wants us to live.)
    
2. Give you the tools needed to create your own style.

While I still appreciate the writers mentioned above, especially the ones that have gone before me, I don't go to them much anymore. I've moved on from them to further hone my craft. But I still love to read. As you go on on your journey as writer, you should be able to do the same.

To be clear, this isn't about one-upmanship. This is about humbly learning from each other. Humility is key to grow as a writer. (I wish I would have learn that from sooner.) If we adopt this mentality, it makes for a much freer, more innovative, and better world. Think about what I'm saying.

Postscript

I will go on to say, if it's possible, you should read more and write less. When I was younger I would have balked at this advice because I was overly eager to become a professional writer. Looking back, I probably would developed my style earlier on if I would have read more. But would it have been style that I have today? Only God knows the answer to that. While this clip in context is about reading more and debating less, I believe there are grains of truth, where we can apply it in our own writing. Even Warren Buffet gives his reason why reading a lot is crucial. He also elaborates on this here. If we read more and wrote less, myself included, I believe there would be far less noise and better, wiser writing out there overall. Hope this helps.

Don't Trade Your Passion for Glory

There's a line in the song "Eye of the Tiger" by Survivor where it says:

You trade your passion for glory

This song speaks volumes of truth about perseverance, which is the only way to get better. But for this post, I'm going to focus on this line. We must be careful not to trade our passion for glory. If you seek to glorify yourself, you will lose the reason why you got there in the first place. It's far better to keep your passion alive and labor away in "obscurity" than to get accolades from others and in the process your passion dies. And when passion dies, you lose the core of your craft.

Glory is a Siren. Though she calls in a seductive voice and she is beautiful, don't go and embrace her or you will "die." It's too easy for us technical writers or writers of all stripes or anyone else for that matter to get drawn in by her songs. Resist her! She is fleeting. People are fickle. One moment, people love you. The next, they revile you.

There's nothing wrong with success. If you worked hard and got there honestly, then God bless you for it! Don't beat yourself when you're successful. But be on guard! Make sure you don't let the glory get to your head, you become arrogant and dismiss those who helped you along the way.

Passion may not at first look as beautiful as Glory. But if we look again, Passion's beauty is deep within and shines through. 

Glory only has the surface beauty but her heart is hollow. Passion is full of simple and pure innocence. Passion will be there and she inspires you to persevere and to be creative. Glory will fade away and move to another when the winds of trends blow her toward another direction. So hold onto Passion. Let Glory go!

For Passion is a faithful soulmate. Glory is a perpetual adulteress.

Passion survives. Glory dies.

Being the Best, No Thanks

I'm not interested in being the best writer there is. I'm okay with others with being far better than me. It's a pipe dream to try to be the best there is. 

Why do I say this? Before I became a technical writer, I remember an acquaintance, he was an old cat who happened to be a jazz bassist, once told me something insightful. He said "no matter what you do, there will be always be someone better than you."

Constant one-upmanship is futile. Supposed you get to the top, it's only matter of time before you get knock out of there. What's the point? Life is too short to pursue this vapid phantom. How much damage can you do to yourself and others when you focus on being the number 1 writer? There's so much more peace when you let this go and just focus on writing.

I'm just interested in doing the best I can as a writer. My focus is on the craft and to continue to grow as a technical writer. I'm not interested in competition. I'm not interested comparing myself to others. Those writers, especially well-known ones, are who they are. I'm just me. God has blessed me with a technical writing career. He has given me a freedom in obscurity, yet given me and my family a well-compensated space to do what I love. I'm just interested in doing the best I can and let the rest follow.

Writing should be about quality, not quantity or prestige. It should be about the craft and creative process that goes with it. I still get a joy in designing documentation, even if it's not "the best".

For however long I can keep writing professionally, I resolved to do this:

And whatsoever ye do, do it heartily, as to the Lord, and not unto men; -- Colossians 3:23 KJV

Perpetual Problem with Woulda, Coulda, Shoulda

When we look at back at something, let's be honest we all do this, and say I coulda have done this, or I woulda done this instead, or I shoulda done that, there's a problem if we let these thoughts go unchecked. The problem is we'll be stuck in a perpetual loop of regret.

Let's suppose we could go back in time and do X instead of Y. If we did X, then we'll say the same thing that I shoulda, coulda, or woulda done Z instead. Let's say you do Z, then we'll say same about A and B and so on.  But it's not just an neverending chain of things of we could have done. What about the neverending chain of events that would have been affected from the things we didn't do because we choose the alternative path?

Let's say we were able to do Y instead of X. How would it affect the world surrounding X if we didn't do X or maybe it would have affect W? 

It's maddening to think about it. So it's maddening to be stuck in a perpetual loop of woulda, coulda, shoulda.

Don't get me wrong. Reflecting on the past is good because it can help us learn from our past mistakes, grow from it, and help us move forward successfully. But if we're not careful, we end up dwelling on the past and fall into trap of endless rumination and perseveration. 

This is true with life, careers, and even documentation.

When we create documentation, though there should be fundamental questions to ask before you start, there are different ways to approach it. Different circumstances require different approaches. In those moments, sometimes, we just don't come at it the best way. I know I haven't many times throughout my career as a technical writer. There are times where I overlook something or didn't document the features as clear as I should have, especially when my knowledge was limited on a subject, or I didn't ask the SME the right questions, or both.

But rather than beating myself up in a loop of woulda, coulda, shoulda, I try to reflect on it and move on. Yes, it's hard to not go back and think I could have done something better. But if I did, it wouldn't be the documentation that it is. And if I could go back, I would probably make the content worse in some ways because of whatever unforseen factors. 

The fundamental flaw with wishing to time travel is we assume we're going to make it better. How do know if we will improve the past? What if we make it worse if we didn't let history play out as it did? What lessons would we fail to learn?

I'm not much of a fan of time travelling stuff or even some alternate history because of this flawed thinking. But I do enjoy the JRPG "Chrono Trigger" and liked PKD's novel "The Man in the High Castle" and still have a couple of Harry Turtledove's novels to read. Beyond that, I have no interest. 

Of course, I'm assuming the worst but it's the flip side of assuming the best. In either case, they're unproven assumptions, so it's fruitless to dwell on woulda, coulda, or shoulda.  The movie "It's a Wonderful Life" shows the downside of this kind of thinking when taken to its extreme. Though it's become cliché, the message is still powerful there. Besides, clichés wouldn't exist if they weren't effective with our psyche. 

The past is there to learn from, even with documentation, so we can move forward into the future. To yearn that we wish we could somehow change the past is a waste of one of the most precious gifts that God has given us: life and time. It will eat away at your soul if you do, where you can't see what's in front of you.

Unlike real life, the beauty of documentation is it can be changed. We can improve it by learning from our past mistakes and continue to improve it in the future.

So rather than pining away about the past or fretting about a future we can't control, let's focus on living in the present. Let's take each day and document at a time. I'm not saying this from a high holy horse. I'm telling myself this as well. I struggle with living in the present but I want to. Let's heed what Jesus said about this. For if we do, we'll have peace and know how to move forward, regardless of our circumstances, even if they're crappy right now.

Matthew 6:25-34 KJV

[25] Therefore I say unto you, Take no thought for your life, what ye shall eat, or what ye shall drink; nor yet for your body, what ye shall put on. Is not the life more than meat, and the body than raiment? [26] Behold the fowls of the air: for they sow not, neither do they reap, nor gather into barns; yet your heavenly Father feedeth them. Are ye not much better than they? [27] Which of you by taking thought can add one cubit unto his stature? [28] And why take ye thought for raiment? Consider the lilies of the field, how they grow; they toil not, neither do they spin: [29] and yet I say unto you, That even Solomon in all his glory was not arrayed like one of these. [30] Wherefore, if God so clothe the grass of the field, which to day is, and to morrow is cast into the oven, shall he not much more clothe you, O ye of little faith? [31] Therefore take no thought, saying, What shall we eat? or, What shall we drink? or, Wherewithal shall we be clothed? [32] (For after all these things do the Gentiles seek:) for your heavenly Father knoweth that ye have need of all these things. [33] But seek ye first the kingdom of God, and his righteousness; and all these things shall be added unto you. [34] Take therefore no thought for the morrow: for the morrow shall take thought for the things of itself. Sufficient unto the day is the evil thereof.

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.

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.

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.