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.

 

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.

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

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.

Word is here to stay, at least for now

Whether we like it or hate it, Microsoft Word is here to stay. (At least, for the foreseeable future.) After all these years, I've realized beyond doing basic stuff and slightly beyond that, I would avoid using Word when creating very intricate technical documents. But, I don't let that be the case anymore.

Long ago, when I was younger and stupidly dogmatic, I got into a heated argument at a meeting because someone suggested we use Word instead of Adobe FrameMaker for our manuals. Mind you, the documents were an average of hundreds or thousands pages long. I rebuffed the guy who suggested it and said in an exasperated manner Word would screw up our documents because of the sheer size and everywhere else with it. I dogmatically told Adobe FrameMaker was the tool powerful enough to handle this. 

Oh, silly, silly me. Where is FrameMaker now? It still exists but it's not as widespread as it once was in technical writing circles. The claims I made about Word no longer hold water because it continues to evolve. Word can handle immense docs. I have done them in Word, cross-references and all. (My book was done in Word eventually. I first wrote it in a flavor of Markdown.)

If you want to see how intricate Word can get, try opening the Developer tab. I barely scratched the surface with this function, but I can see how robust this is.

I'm not slighting FrameMaker. I still think it's a great tool, especially with complex technical documents. I used it for many years. But who wants to use a tool that's very overwhelming at first and not very accessible to the average user. (Yes, this can include technical writers.)

Word allows for more collaboration with SMEs and others with comments. Word has an easier learning curve. It's those like me who overthink on how to use it. 

And regarding sheer size of documents, I could have avocating breaking them in smaller documents. Or, if the audience didn't need to know more detailed technical information, I could avocated in removing big swaths of material to what was important to know. Looking back, I would have things differently. But it's not good perserverate over things. I did what I thought was best at the time. The important thing is learning from it and move on to make better choices.

I've learned to appreciate Word. Slowly but surely, I feel more at ease creating documentation in it. What's the secret?

The key is to work with the tool, not against it. We need to accept Word for what it is and not try make it something that's not.

I have seen technical writer conferences advocating for other more highfalutin tools. Something the average person isn't to use. Nor is it cost effective to purchase something like this. To me, it's seems like they're avoiding this simple tool. But what do I know? I'm just some schlub who types words on a screen. 

Now, Word falls short. But so do all other tools on this planet. You just have to decide what's most accessible to use. Word happens to one of the most ubiquitous. So, make the most of it. Why fight against something that's easily available?

But, tools shouldn't make up your technical writing prowess. It should be skills. So, if you only had a stick to write with and the earth is your canvas to create a document, then it shouldn't be a problem. 

Only One King and None of Us are It

Disclaimer: This post isn't the typical water cooler talk for technical writers. For some, such as myself, maybe it is. So if you're looking for a post related to technical writing, feel free to skip this one. Otherwise, read on.

There's only one King and none of us are it. In a time where we can make everything about ourselves, and you don't have to look far to see this, this truth is still radical and threatens the idea that we're the center of the universe. 

So who is this King? This King is no other than Jesus Christ. He said so Himself to those who were with Him sometime after He rose from dead. See below.

"And Jesus came and spoke to them, saying, “All authority has been given to Me in heaven and on earth." -- Matthew 28:18 NKJV

(If He's King, then why is this world  screwed up? Short answer: it's us. If you think this is all nonsense, that's your perogative. You're entitled to your beliefs and that's fine, but so am I.)

I'm glad He's King and I'm not. I would be a stupid king if I ruled over anything. It took me a while to see that. When I handed my life over to King Jesus, it's been freeing. I don't have to try to play this one-upmanship game with anyone anymore. Or, try to make a name for myself. And for what?! Even if I were a famous writer, it would only be a matter of time before someone else knocks me out and I'm forgotten. The prices you need to pay to get that fleeting place is futile and vacuous, especially if you trample on others or sell out to get to the top. Not worth it.

Instead, Jesus has given me something better. Something that lasts. And He's helping see others differently. Instead of seeing others as potential competitors, I'm seeing others made in God's image, whom I can cooperate and collaborate with. It's far more rewarding when I've worked with others on writing projects. When I've done, it's goes way better than what I can imagine. 

Though I have a long way to go, my ambitions are fading away. I rather seek Jesus's ambitions instead (but I believe I fail at this.) I don't see the point in seeking great things for myself anymore. I once did. I had grand ideas when I first started out. I thank God those never panned out. But it's a struggle, since there's an instrinic egomaniac trap when you become a writer. But to be a good writer, it's a trap you must avoid at all costs.

I rather follow my King by loving and serving others. (Sadly, I wish more who claim they follow Jesus would attempt to do this. But, they'll have to answer to God for this. But, I too have a long way to go.) And, if I can do so through writing for as long as I can, then great. If not, then that's okay too. 

Jesus is the King. I'm not it. And that's okay with me. Maybe if more relinquished their control, especially those who try to have it over others, and gave it to King Jesus, then this world wouldn't be so screwed up.

When There's a Need, Write, but What If...

"See a need, fill a need."

That's good advice with innovation, providing goods or services to others, and writing, especially with technical writing. 

Whenever I've ran into different things or got into conversations with people whether it was about a user interface (UI), an API endpoint, how to maintenance or install a part, or a procedure, if there were no documentation on them and I was able to do so, I would write something to fill that need. Or, if the documentation was poor and if possible, I would try to improve it.

I took this advice of seeing a need and filling a need when I wrote my novel, The Unlikely Messenger. At the time, I found no one out there who wrote something similar, especially with the challenges the main character had to face. The theological answer for my character's condition were either lacking or weren't really acceptable (at least for me). So what I did I do? I slowly over 10 years wrote a novel. Looking back, I don't know whether I should have written the novel. Maybe there was no need to do so. But what's done is done. And, I'm fine by it. In the end, I'll have answer to God about the book.

But what happens when there's no need to fill? Or, what happens if there's someone else already wrote similar? So they seemingly filled that need.

The short answer: Don't write it.

Yes. That's right. Don't write. You're wasting your time and energy. Why be just another voice saying the same thing, especially if you don't need to? You don't see, or you shouldn't see, two or more documents explaining the same thing about such and such. So, use your writing for things that don't exist yet. 

Besides, you can always look to find needs to fill. It just may not be in the places you're looking at. So, look elsewhere. But if you can't find those needs yet, then wait. If you need to, do something else while you wait. If you also feel like you need to, freewrite or journal. But if there's really no need to write something, then don't write it. (But, if you feel like you have a unique idea, then by all means write it out.) In the meantime, what can you do is observe what's around you and listen to what others say. When you do that, you'll end up writing something eventually.

As for those who've written something already, if you think you can say it better, do so. Otherwise, step aside and just direct or refer others to that piece of writing or documentation if they're looking for such and such. Writing for ego's sake is empty and shallow. Been there, done that.

But I suppose if we only wrote what's necessary, then that would probably eliminate most content out there. Maybe this blog belongs in that pile. Hmm.