Unless it's documentation, I don't do major revisions

That's right! I don't do major revisions once I publish something. Once it's out there, I move on to the next project. The only exception is technical documentation. By nature, technical documentation is fluid because it's contingent on the product or service it documents. So if there's a major update to a software, I would expect major changes to the documentation. Even with minor software updates, depending what's changed, I would expect changes in the documents too.

We technical writers are constantly writing, editing, and revising materials when we're actively working on projects. Some may call it a curse. I call it a blessing because we get further use and hone our craft.

So my rule of no revisions doesn't apply to technical writing or technical documentation. I'm talking about published works outside of this realm. 

Erases Your Growth

When we go back and do a revision of work we've created and published, it erases the growth we've made as writers. (I'm not talking about works that need periodic or regular editions. In those cases, you would need revisions to keep your material relevant or accurate.)

My earlier work isn't good. So what! While I still don't believe I'm a good writer, I've seen continual growth since I dedicated myself to the craft.

Growing Since My Novel

When I published my novel The Unlikely Messenger in 2019, it was a feat. I was in knots whether it was good but I pulled the trigger to get it out. It was sitting somewhere tucked away for years. My thinking was if I wrote something and I'm okay with it, then why leave it unpunished?

I'd probably cringe if I looked at my novel again. It's been a while. I know I've changed since then, especially in matters of eschatology. I've also tried have a more consistent Christian worldview since then, though I still have a long way to go.

Would I write a dystopian novel again? No! While tyranny, evil, and injustice is rampant, dystopian societies don't last for the long haul. They either end in overthrows or implosions. History shows they always go into their dustbins where they belong. So if the powers that be managed to create a one world government, it would be destined to fall apart. Even if God doesn't intervene, people's egos, especially those in power, will make it implode or nations would break away anyway after getting tired being told what to do.

But would I go back and make revisions to my novel? No! For if I did that, it would no longer be the story that I wrote. I'm okay with the follies, blind spots, and probably bad writing that's in there. It's a benchmark for me to know where to go from here.

I Let Blog Posts Stand, Well Mostly

I don't even go back and revise my blog posts either. If I went back to say it better, then it would no longer be the posts that I've made. The only exceptions would be spelling and grammar errors or a factual error if I notice. Besides that, the posts stand.

Cancel Culture Nullifies Progress

The cancel culture is beyond ridiculous because it doesn't allows us to be humans. Are there stupid or evil things we all may have said or done? Yes! No one is above this folly. Let's discuss them honestly. Let's own up to them. But to cancel people for what they said or written years ago even they don't believe those things anymore, and even now repudiate those previous beliefs, negates their growth. Those past errors and evils are there for us to learn from. (I'm not talking about people that are still doing and saying stupid and evil things.) If we erase or cancel them, then we're more apt to repeat the same evils or follies because we'll no context or history to move forward from. 

Be Careful about Embracing this Mentality

Be careful about embracing the cancel culture. If we're going to be consistent with embracing the cancel culture, we have to erase everything, including ourselves. As Jesus said, be careful about the measure we use for it will be used against you.

Any writer worth their salt should understand the danger of the cancel culture mentality. This mentality will destroy vigor in all writing, including technical writing. I'm glad people have pushed back on it. I hope this absurdity goes into its dustbin. I digress.

Don't Erase Your Mistakes

The easiest way to hit a plateau where your writing becomes sterile is where you're obsessed with erasing imperfections. How will you know that you've grown and progress as a writer, if you can't embrace your earlier mistakes? Accept that you made them. Learn from them and move on. 

Be Human and Understand the Journey

We as writers must be at peace with what we put out, even if it makes us cringe. I still cringe at earlier technical documentation I've written, even if it was a short time before.

Seeing the progress you've made as a writer is far better and more rewarding than trying to have everything look and sound "perfect."  That sounds boring and machine-like. Be human. Understand we're all on a journey as writers. 

Writing for Validation? No!

There are many reasons to write. But there are reasons not to write. Validation is one.

If you're writing to seek approval, then you're going to be disappointed. While it's crucial for writers, especially those of us who are technical writers, to build bridges with the audience you're trying to reach, you're not going to find validation from them. 

The audience doesn't care who you are or what you write. Ultimately, they're just looking for information and content they want and they move on once they get it. If they return, it's because they're looking for what they want, not you. Now, some may counter me and say they like certain writers. Is it the writers themselves they seek, unless you're some nut job stalker, or stuff they write? You know the answer to this question.

If you're looking for approval with your company, good luck with that too. You might get some unsolicited advice if you're constantly asking Subject Matter Experts (SMEs) whether your writing is any good or your documentation has any value. They'll let you know if they're not happy.

Taking constructive criticism is one thing. We need it to improve as writers. Writing is an ongoing process. We only get better by doing it constantly and humbly taking feedback. Heck! You can even send surveys to your audience and the SMEs to see how you can improve documentation. After all, documentation is about serving your audience. But seeking validation is another. It's an unhealthy extreme. Validation is a phantom prison!

You're afraid of what others think and you ruminate about the possible criticism or some half-cocked comment from someone. So, you try to appease them and you lose your voice in the process. But in reality, they're not even thinking about you at all.

The fatal problem with seeking validation is it makes you the center of the universe.  But guess what, you're not the center. 

Seeking validation is in the same vein as comparing yourself to others, but it takes it a step further into narcissism. What one really wants is accolades and praise? What someone who seeks validation wants is an echo chamber. Let's be honest. Do any of us go around seeking to find criticism, even if it's constructive? No! We prefer to do things our way. I'm not saying that's right. I'm just saying that's what we tend to do.

So why seek validation for your existence as a writer, particularly a technical writer. Let's keep our heads down and power through to great documentation. Leave the rest up to God. Seeking validation is a big waste of time and energy. Don't do it! Be humble yet confident in your abilities. But if you're writing only because you want the approval of others and want people to extol you, then maybe you shouldn't write at all.

Technical Writing: Systematic Advantage

When my wife and I watch campy movies, there's a typical theme of a writer who has writer's block. The writers in these movies try to write something but can't. Or when they start writing on the computer, they let out a sigh, deleting everything till it's a blank screen. While these scenarios are exaggerated, there is some truth to it.

It's difficult when you must create something that relies on your mind. I know. I've written a novel before. Writer's block is always lurking around the corner. When you write, that constant inner critic is always trying to lead you to that corner. Those who are career authors, I don't envy them. God bless them for keeping their imagination going, though they struggle to craft meaningful words on the pictures they're trying to paint.

We technical writers have a systematic advantage over our creative counterparts because we document things based on what we can see and use. (I mean systematic, not systemic because while the writing process is universal, we're in a different category than creative writing. I suppose you could say we have a systemic advantage. In any case, we have an advantage.) If you're documenting user interfaces, we can walk through each step of the way to help us write. So the chances of writer's block decrease, though it can still happen.

Should we feel ashamed that we do have this over other writers? Absolutely not! But we should be thankful that we don't have those blocks. Of course, our blockers are from SMEs, developers, or whatever. We can't write anything until they're removed. But once we remove these blockers, we are to free to write till we're done. Our blockers are external not internal, so we have an advantage. So let's use it to create great documentation. Since we don't suffer writer's block like the creatives, there's no excuse for sloppy documents. Am I saying perfection? No! There's no such thing as perfect documentation. But we can strive towards excellence.

So, my hat goes off to you creatives for doing what you do. Keep writing! Thank you for building those worlds for us to enjoy and think about.

 

Whose Glory?

"So, whether you eat or drink, or whatever you do, do everything for the glory of God." – 1 Corinthians 10:31 NRSV

Though I strive to uphold this Scripture, it also makes me pause. Whenever I'm writing, whether it's a story, documentation, or this blog, this nagging question echoes in my mind: Whose glory am I doing this for?

Then, the answer comes or follow-up questions come. Am I doing this for God? Or am I doing this for myself? And if I say I'm doing it for God? Am I really? Or is that a convenient excuse I give myself to do what I do.

No matter how hard we try, we can't avoid this question. So we must honestly answer it.

This question isn't only for writing. It's everything. So why is this question important? Well, it'll steer us toward why we're doing something, including technical documentation. 

On the surface, technical documentation seems to glorify the organization. The organization tells its audience they have the answer they are looking for. If its audience is grateful or in awe over the information, the credit goes to the organization. But who wrote the documentation? If you're a technical writer for an organization, you wrote it or those on your team did it together. 

Now, if you believe your organization is the best and you're truly writing for it, then, by all means, do so. But are we deluded ourselves? Isn't there something we get out of creating technical documentation? Isn't there a sense of accomplishment or pride? You may be a better person than I am. When I create and deliver technical documentation, I get a rush and the satisfaction of a job well done. It's a great feeling when I get stellar feedback.

So, on some level, I'm creating technical documentation for my glory. Even when it's a team effort and I happily give credit where credit is due, I still get something out of being a part of a bigger effort. Also, I enjoy creating technical documents because I like helping my audience clearly see the answers they're looking for. Though I want to use technical writing to help put food on the table for my family, I like the feeling that I'm doing my part. So it seems inescapable that I'm doing all this for myself.

If we're completely honest with each other, you would say the same thing. So what do we do? Do we just admit we're really narcissists and live that out? If so, see where that takes you. Or do we strive for something better? 

I think the better road is to acknowledge this selfish element and strive to create documentation for God and others. Like writing, striving for this is a life-long goal. Even if we're far from this, it's worth pursuing. 

Though I'm far from perfect and I don't have it all figured out when I've asked God to help create documentation for Him and others, He has helped me create something far better than I could've imagined, especially when I've collaborated with rockstars in their fields.

Honesty with this question is the way to move forward. But be careful! It might lead to other questions, such as: Is this something we should be doing? If not, should we do something else that's not for ourselves? This includes technical documentation. 

To deepen ourselves in our trade, we must reflect on why we do what we do. Whose glory? Us, others, God?

When you Doc as Code

What is doc as code? Doc as code is basically two things. One, it's creating documentation with the same tools as you would use to create code. Two, it's using similar methods of creating, versioning, and publishing documentation as you would with code. 

What do I think about this? Short answer is context. If you're creating or editing material in a software environment that uses Agile methodology, then you should doc as code. Otherwise, I wouldn't worry about it. If you're in this context, I'll give you a few,  brief reasons why you should doc as code.

Save Costs

The first and foremost why you should doc as code is to save costs. Tools, licensing, even training on how to use tools all cost money. It also costs time to maintain and invest on different tool sets. If you're using the same tool to create code and documentation, you can save on both. No further explanation needed. 

Easier to Build Bridges

If you're using the same tool as your Subject Matter Expert (SME), it's easier to build bridges to create documentation. If you're using the same tool(s), it's easier to collaborate together on documentation. This doesn't mean you have to learn to code. (But it might help to know a little bit.) In some ways, using the same tools and releasing documentation the same way as code is like you're speaking the same language as your SME.

More Unified Experience

If you doc as code, then the release of software and documentation is much easier. The obstacle of getting your documentation in a certain format, so it goes with the software release is no longer an issue. You just have to make sure you and your SMEs are working in sync to make sure the documentation reflect what's in the code and vice versa. And that can be challenge in itself, so why would have other unnecessary issues to prevent this from happening.

To find out more about doc as code, check out these resources:

https://www.writethedocs.org/guide/docs-as-code/

https://www.gitbook.com/blog/what-is-docs-as-code

https://github.com/readme/guides/code-as-documentation