Search This Blog
Thursday, September 14, 2023
Friday, May 19, 2023
Thursday, April 20, 2023
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?
Thursday, March 30, 2023
As technical writers, we must be thorough when we create or edit documentation. If we're not, then we might present shoddy, confusing, murky, or incomplete information to our audience. But being thorough doesn't mean you should be pedantic.
Pedantism is annoying at best and destroys relationships at worst. It's unnecessary, short sided, and stupid.
But what's the difference between being thorough versus being pedantic? For us, being thorough is carefully making sure the documentation is clear and helpful for our audience. Or when you're dealing with SMEs, you ask good or the right questions to get the information you need. But being pedantic is pointing out, or if we're being honest with ourselves, picking on small details that don't matter.
Does it compromise the clarity of the documentation? If not, let it go. But if one wants to insist these details are important to point out, then think carefully and honestly. Are they important? Seriously, are they?
Or, if there's a small error or limitation and you can safely assume (it's okay to assume sometimes) most people are going to figure it out, then let it go.
How about speaking with others? Are you going to point out to small inaccuracies in their word choices because it's not to your liking?
One of the worse forms of pedantism to me is when someone corrects someone's grammar or pronouncing when they speak. Why?! Did they ask for help speaking? What are you doing other than showing how smart you are and showing how stupid you think someone is? Are you that thin skinned that you can't possibly hear an imperfection? If you understand someone's point clearly, then why do that. All it does is sour relationships. If you want to be a successful technical writer, it goes beyond great writing, grammar, and editing skills. It's also about building great relationships. Without it, you might have nothing to document.
Don't think I'm okay with bad grammar. I just save correcting and improving the grammar for documentation. And even then, the grammar rules we uphold aren't as ironclad as you think. (While these rules give structure and meaning to any language, they aren't infallible. Sometimes, these grammar rules are fake.) Don't believe me. Look it up.
If given the choice, I rather take a clear sentence that they may not be perfect grammatically, than one that's "grammatically" correct yet clunky in its explanation.
Guess what? No matter what you do, no documentation is perfect. No tool is perfect. No one is perfect. Nothing except for God is perfect. It's an exercise in futility if you strive for that. Instead, strive for clarity, technical accuracy, and good document design the best you can. The rest will take care of itself. If you need to make improvements, then so be it.
Besides, you wouldn't want perfection because there would no longer be any innovation, whether on the subject you're documenting or documentation itself. Think where that ends up, if there's nothing to improve because of perfection.
Pedantics, like legalists, focus on the minute details but not the big picture. It reminds me what Jesus said when He rightly rebuked the Pharisees for their pedantry. Check it out.
Also, pedantics may like to impart their "wisdom" on others. But they don't like when someone else does it to them. If a pedantic person is honest, then they don't like that. It reminds me of what Jesus said here about the measure in judging people. Check out what He says here. If anyone wants to be pedantic, then they'd better be prepared for other pedantics to correct them.
If not, why carry the weight of pedantism around? It's not just a burden others, it's also a burden on yourself. Dump pedantism into the metaphorical ocean. (Don't actually dump anything into the ocean. Seriously. Don't. Let's keep it clean, if we can.) Free yourself from it. If you don't, it can hinder you from growing as a technical writer.
Now, it would be hypocritical of me to lance pedantism from a high holy horse without admitting my own faults. I've been guilty of having some pedantic tendencies in the past. Mine was trying to absolutely uphold style guide conventions, but I didn't take context into account. While I still think style guide rules and convention are great, they're not absolute. I'll also still uphold style guide conventions, but if a sentence sounds clearer and more natural and it "breaks" with convention, then I will choose this sentence over some arbitrary rule. My focus is on the big picture: Creating clear and helpful documentation for the intended audience.
By trying to get away from these tendencies, it's helping me to continue to grow as a technical writer. I'm able to work with liberty and confidence. And my relationships with SMEs have also improved over the years.
Life is too short to be pedantic. Focus on the big picture. Is the documentation clear? Is it helpful? Writing in active voice goes a long way with this. Is it for the intended audience? Building genuine and good relationships with SMEs will help you understand your audience. Do it with a smile and laugh.
Don't let the minutest of details distract you from that, especially the ones that don't matter in the big picture. When it comes to pedantism, that adage "the devil is in the details" applies. So, let's prevent the devilish details from winning out.
Be thorough, not pedantic.