- 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.)
- Give you the tools needed to create your own style.
Search This Blog
Thursday, March 19, 2026
Read to Write
Friday, February 27, 2026
Don't Trade Your Passion for Glory
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.
Passion survives. Glory dies.
Tuesday, February 17, 2026
Being the Best, No Thanks
Tuesday, January 13, 2026
Perpetual Problem with Woulda, Coulda, Shoulda
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.
Tuesday, September 9, 2025
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.
My Story: Creation of a Style Guide
Tuesday, June 17, 2025
An Alternative Way of Explaining
- 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.
Thursday, June 5, 2025
Why I'm Not Afraid of AI
Tentative Stance
AI and Writing
Human Nuance
AI is just a Tool
AI Depends On Us
Let's play the worst case scenario
Let's play the not so worst case scenario
Those with Little Scruples
Folly on Display
Their Lack of Scruples May Create New Fields
Possible Counter-Strategy
AI is a Powerful Tool but Ultimately Powerless
Wednesday, February 26, 2025
Freedom in Obscurity
- Too much pressure to perform
- Have to constantly care what others think
- Your life is utterly scrutinized
- You can lose yourself in the process
- You can get a big head
- You can forget why you love what you do
- Never enough
Friday, October 4, 2024
Writing for Validation? No!
Friday, June 21, 2024
Whose Glory?
Friday, January 5, 2024
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
Easier to Build Bridges
More Unified Experience
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
Friday, December 8, 2023
Grateful For This Blog
Friday, May 19, 2023
QA Your Docs: Final but often rushed step
Thursday, April 20, 2023
More Thinking, But Don't Overthink
What if we thought more before we said or wrote anything? I like what Warren Buffet said about how spends his time thinking. This sitting and thinking can come in handy as technical writers.
Before we create documentation or in the process of creating one, it might help to stop and think things through. (This will especially be handy if you have a product to play with.) We might get clarity as we walk through a mental journey to overcome some huddles.
Save Time and Effort
Thinking more might save you time and effort on documentation. Rather than fuddling around where you might end up deleting either half the documentation or the whole thing, why not think things through before you write? Jotting some quick notes can help you see where you need to go. (While I believe deleting what you wrote previously is a part of the writing process, there is such a thing as overediting, which I think is a part of overthinking, which I will get into in a bit.) Thinking can help you create a map of where you want to go or prevent taking unneeded steps.
So, if we were documenting a product and we had it in our head initially to create one giant document, but then as you think it over, it turns out it would be better to have a series of smaller documents. Or, let's say you thought at first you need multiple documents but you realize only need one document. Or finally, the product is so self-explanatory, it doesn't need documentation at all, so you can focus your efforts elsewhere.
Thinking things through can help us with this, rather making rash judgments where we'll regret this later. We only have so much time in our lives, so we need to be prudent with what we do.
Writing is Thinking–Probably Not
Some might contend that "writing is thinking." I see what they're saying. I agree with this to a point, but in the end I have to disagree. Writing and thinking are two different things. Thinking is a mental process in your head. Writing is a creative process that shows itself in print, audio, or screen. Thinking may help you get ready for writing but it's not writing. If you think otherwise, that's fine. We can agree to disagree.
Don't Overthink, Just Write
Just like you can overwrite or overedit something, you can overthink something. Overthinking is bad. Like over-engineered or overwritten work, it can be confusing at best, where you have too many caveats, complexities, or features. At worst, it can lead you to a mental paralysis where you can't write anything at at all.
After thinking something through, it's time for you to write and let the chips fall where they may. When it comes to writing, I agree with Ray Bradbury. I like what he said about writing. In context, he was referring to creative writing. But I think we can apply this to technical writing.
I have seen other technical writers, and I've experienced this myself, paralyzed to create documentation because we overthought stuff. We were trying to take too many things into account. When we commit to writing, we just need to need write it out, refine it, and publish it. Worst case scenario is we need to revise the documentation. Revising documentation is a part of life as a technical writing. This is especially true if you write for software applications, where updates are the norm.
But first, what if we sat and thought carefully, without overthinking, through things before we did anything? I wonder how life would be?