Search This Blog

Thursday, March 30, 2023

Be thorough, not Pedantic

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.

Wednesday, March 8, 2023

Show, Not Tell–Bring Documentation to Life

As you've pursued the writing craft, you may have heard or read the following:

"When you write, show not tell."

This is great advice. Showing rather than telling brings life to your writing. I struggled with this when I first started out. I still struggle at times. But what does it mean to show rather than tell? Let me attempt to give an example:

Tell: Toby went across the rocky, cratered terrain on his rover to get to the city.

Nothing wrong with this sentence. It describes what's Toby is doing. And there's nothing wrong with just telling your readers what's going on. For me, it's simplest approach. But if you do this with every single sentence, your writing might become flat.

Show: "Uoof," Toby cried as he went over a rock. "This is no easy cruise. Whoa!" Toby sharply turned the steering wheel of his rover to the left to avoid falling into a crater. "That was close! Just a few more miles before I get through this rough patch. I see town up ahead."

Here, showing adds dimension to what Toby's doing.  It's more than just writing more sentences and adding dialogue. Far from that. It's about painting an in-depth picture, especially if it helps the story along. 

But with all great pieces of advice, we can take it to an extreme. If we show everything, then we can get an overwritten mess, where you might overwhelm or confuse readers. You might end up with written pictures without any context to link them. Narration is telling a story, regardless how you look at it. Knowing where to show and where to just tell is tough and can only come through practice and time. The key with showing is using it where it better communicates you're trying to say.  

Showing in Technical Documentation 

One of the advantages with technical writing versus other styles is showing versus telling is easier to do. I'll explain how. Rather than crafting a narrative like the example above, you can use screenshots and other examples in certain parts of document. 

If a flowchart or a screenshots succinctly explains a concept or an action better than writing out paragraphs of text, then use the picture. The cliché "a picture is worth a 1000 words" is true in technical writing. 

If you're writing something like API documentation, then showing code examples and call responses will help communicate your point across. I would venture to say with API documentation, code examples and responses are more important than the writing itself. So, showing is crucial. For an example, see one from Square.

I would include hyperlinks in showing rather than telling, if they better showcase what you're trying to say. 

But you don't want to place screenshots, code examples, or hyperlinks just for the sake of doing it. You risk having a bunch of examples without context.  Doing so, might confuse and overwhelm your audiences. You want to place examples in your documentation because they better clarify information you're trying to convey. Knowing where to place visual examples instead of writing is key to good documentation. 

Showing examples through code examples, screenshots, and graphics will help your technical documentation come alive, especially with clarity. Sometimes, your audience might use your examples as a shorthand way to comb through the documentation. So, make your examples count.