Search This Blog

Monday, May 9, 2022

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. 

Monday, April 18, 2022

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.

Saturday, March 26, 2022

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.

Thursday, October 28, 2021

Bittersweetness of Finishing

Whenever I finish something, especially when it was a difficult journey to get it done, I get a sense of satisfaction that I finished what I started. It's even more rewarding when the purpose of what I worked on will help others. It feels good.

But I can also get a sense of sadness when it's over. If I enjoyed working with others to finish a document, I can get sad that I'll never worked with or see them again, at least not in this life. 

Finishing something is bittersweet. But that's way it goes with all things writing. All documents, books, projects, contracts, and even jobs must come to an end. Every written work and what surrounds it must have a beginning, middle, and end. That's how it goes. I'm okay with it. I actually look forward to ending a work. But there's a sting to it, especially if you don't know if there's anything after it.  

But, bittersweetness can go both directions. You don't have to end the sweetness of finishing with a bitter taste. It can also go this way: There may be a bitter taste at first when you end something, but there's also a sweetness, sprinkled with scariness too, on what happens next.  A sweetness to writing new things, working with new people, and an opening to new opportunities and possibilities. It can be scary and unsettling but also sweet and exciting.

You can't taste what's sweet unless you can also taste what's bitter. So let me close with this apropos scripture:


Wednesday, October 6, 2021

Ask Two Questions, Maybe Three

When you create a document, you need to ask two, maybe three questions. But at least, you need to ask two. So what these questions? They are:

- What is this thing I'm writing about?
- Who is the audience I'm writing for?
- What kind of document am I writing?

Why does it seem I waffle between two or three initial questions? Well, you may not need to ask the third question because it may come up naturally in your conversations with the SME(s).  Only ask the last question if you need to. Otherwise, the SME(s) may lose confidence in your ability as a technical writer.

But the first two questions, you should definitely ask when creating documents, especially if you're in a new setting. So why these two questions? Well, these two questions will help set the direction of your documentation. 

If you know what you're writing about and who you're writing for, it'll help you know what kind information to write in your document. Let's say you're writing a user guide on how to use a software for storing recipes and your audience are home cooks and chefs, you're not going explain the technical inner workings of the application. You're just going to show them step-by-step how to enter and save their recipes. That's it. 

When we approach documentation, we should take Mark Twain's advice when writing good stories. He said:

"A successful book is not made of what is in it, but what is left out of it."

So, let's focus on what to write and chisel out the rest. Our audience deserves it.

Wednesday, August 18, 2021

What is a Technical Writer?!

This question popped in my head after one of my kids asked me the main job of what I do. So, it reminded me of the exchange between Dracula and Richter Belmont at the beginning of Castlevania: Symphony of the Night.

Let me pick up the part of this exchange to parody Dracula:

       "What is a technical writer?!" 

       (Hear the laptop casted from my hand             and crash to the ground)

      "A herder of cats with a smattering of               writing?!"

       "But enough words! Let's document!"

Thursday, June 3, 2021

When Is It Enough?

Recently, I thought about the ending of my own novel, The Unlikely Messenger, I wrote some time ago. As I thought about it, I said to myself maybe I don't need to publish another novel.  Maybe that's enough. 

Whether I'll follow through on this, I don't know. Either way, I'm okay. But there needs to be a point when something is enough. You may disagree. You may say why not keep going? 

If you say there's no point of enoughness, then nothing will be ever be enough. And if nothing is enough, then you'll never be satisfied. And if you're never satisfied, you'll never find what you're looking for. It'll just endless striving for more like chasing a pot of gold at the end of a rainbow. Where does that lead? Where does that end?

We could go some in so many directions with this. But since this is a technical writing blog, I'll try to keep it writing related, especially technical writing.

Creating Enough Documentation

While I believe in documenting every important procedure, function, and feature, I believe there's such a thing as over-documentation. 

If we have a plethora of documents floating around saying the same thing over and over, then we may confuse, frustrate, and overwhelm our audience. Which ones should they read? Do they need to read them all?

By creating a vast sea of documents rather than a deep pool of helpful instruction and information, we may end up drowning them with information overload rather helping them dive in to find what they're looking for. So, they may forego all our documentation or go to someone else who can help them. 

You don't combat the common problem of 
under-documentation with an overreaction of over-documentation. The key is creating documents for every piece of important information.

So how do know we created enough documentation?  

Maybe one example can help. Let's say you have the same series of products but they're just different models numbers. I don't think you need to create a document for every single model. You just have one document for that product and note the differences of the model numbers, if any, within that document. 

I'm aware if we took that to the extreme, then we would have documents as big as old phone books. I'm not advocating for such an absurdity. Even with lengths of documents, there has to be a limit of enough. So where is that? If we cover the functions and how to use the product, then this should be enough. 

Writing and Rewriting Enough Iterations

When we create documents, we have to know a point when there's enough work before it goes out to the world.

We can't sit there and write, rewrite, and edit excessively. Otherwise, we'll never get anything out the door. There needs to be a point when it's enough. So when is it that? 

Here's my take. It's neither full-proof nor comprehensive but it works:

 - We covered all the needed information on how to use the product.

- You or a SME walkthrough on using the product. (If it's a service or a procedure, then have someone review it after you're done.)

- Once you finish the document, go through it again and make any fixes or edits. (A couple times through is good but beyond that is excessive.)

- Make sure document gets reviewed before it goes out. Doing a QA on a document would count as a review.

If we've done this, then all we can do is put it out. Sometimes, you just have to publish and cross your fingers or pray that it's all good. But letting anxiety or perfection paralyzing us from writing isn't an option.

While we should strive to create quality documents, we can't expect perfection. It's unrealistic.

If customers find issues with our documents, then they'll let us know. That's the beauty of feedback. It helps us improve. We just have to move in the spirit of enoughness to get things done. When we do that and let go of perfection, we give room for our customers to help us improve documents in ways we couldn't imagine.

Not Sinking into Complacency

This may sound like I'm advocating complacency. I'm not. I'm advocating for contentment. To some, this may sound same. The difference between the two is attitude. 

Contentment is knowing you have enough and you're satisfied. You have a peace in your heart that's beyond words. Complacency is you're settling or you're comfortable at a certain level because you don't want to stretch yourself and avoid hard tasks, even if an actual need arises.

Again, we can go in many directions and levels with this. But I'm focusing on documentation. So how we know the difference?

Knowing the Needs for Documentation

To know the difference between contentment and complacency, we need to look at needs. Does a product or a procedure need a document? If so, then rise to the challenge even if it's tough. If there's already a document, then check to see if you need to revise it. If you simply don't want to, then that's complacency. 

Knowing the needs and simply addressing them helps us avoid the extremes of complacency and over-documentation.

Living with Enough Writing

If we know we've done all we needed to do and said what we needed to say, then we need to be happy with what we've written.

I like what Mark Twain said:

"A successful book is not made of what is in it, but of what is left out of it.”

Twain knew when it's enough in a story. And we writers should do the same.

Unless there's a need, we need to be content with what we wrote. As long as we did our best, we can't live in regret. We have to be content with it. 

Pursuing Enough

Honestly, I haven't arrived at contentment completely, even with documentation. But I want to get there. So, I've been saying all this to myself too. But if I don't, what's the alternative? No thanks. I rather pursue what's enough, even with documentation.

I like what the Apostle Paul said to Timothy about enoughness:

Of course, there is great gain in godliness combined with contentment; for we brought nothing into the world, so that we can take nothing out of it; but if we have food and clothing, we will be content with these. -- 1 Timothy 6:6‭-‬8 NRSV

So, if I can fully arrive at godly contentment, then it'll be enough.