When you don't have all the pieces

When you create documentation, there are three fundamental questions you need to ask.

1. What is the thing you're trying to document?

2. What kind of document are you writing?

3. Who is the audience for this document?

If you get answers to these questions and find the key Subject Matter Experts (SMEs), you're on your way to creating good documentation. But let's be honest with ourselves, even with this information, there's a good chance that you'll still have missing pieces. What do you do then? 

If you're in a circumstance, where you can test the product, say software or API calls, then you can probably fill some of the missing information. But not all technical writing circumstances are the same. Sometimes, we're detached from the subject we're writing about because we're not able to test a product. Going on a limb here, say nuclear technology. It doesn't have to be this extreme. But it could be just simply no way of testing out your subject or product. So what do you then?

One thing you can do is be persistent. As you talk to the SMEs, ask your questions along the lines of the fundamental questions you've asked initially. When SMEs are stumped from your questions, you can ask them who would know. They might direct you to another point of contact or get back to you if they need to dig into this. In any case, finding the missing information for a documentation isn't impossible. It just requires persistent. 

The worst that can happen with documentation, is that you can't write it, because the information doesn't exist and maybe the subject just a concept for now. And that's a planning issue beyond the scope of your responsibilities. Aside from this, if you're persistent you can find the missing information.

It reminds of the game Chrono Trigger with mysterious gray chests scattered throughout in different places and time. When you try open them, it would play a song and a dialog box tells you a mysterious force is keeping it locked. You can still play the game but it seems like something's missing when you can't open these chests. These chests stay locked until you charge up Marle's perdant and that's when you can open these mysterious chests.  

Like the way you need to charge up Marle's pendant to unlock these chests, you just need to find that piece of information or point of contact that help links the missing pieces together. Creating documents can be an interesting quest.

QA Your Docs: Final but often rushed step

Once you've written the docs, it's time to release. Right? No.

Other Technical Writer: But I double-checked the text and the graphics to make sure it looks good. 

Me: That's great. You looked at the docs and made the edits. Editing is step 4 in the general writing process. Every step in the writing process is crucial. But did you QA the docs? 

Other Technical Writer: QA? 

Me: Yes, did you QA?

Other Technical Writer: What do you mean by that? Do you mean I sent the doc to QA? 

Me: Well, you can do that and probably should if you have QA people. But did you QA the doc yourself, especially if you have the ability to do so. 

Other Technical Writer: Well, how do you do I that? 

Me: QAing your documents just means check to make sure the steps you wrote is matching the product is doing. In other words, does your document correspond to reality?

Often Overlooked Step

If we simply take the time and check to make sure the document is actually saying what the product is doing, then it might avoid dissatisfaction from our customers. How beyond annoying is it when the instructions are not only confusing but also don't correspond to the actions or parts of the product? This is probably why many chuck the instructions and try to figure it themselves. For a lot of things, someone can do this just fine. And the instructions are just stupid and useless. But what if those instructions are critical? And, if they try to do this themselves, they and others might get hurt–or killed–because of poor documentation. 

Instead of rushing things and slapping instructions together, let's simply take a little extra time to make sure the documents accurately portray the product. Faster isn't always better. It reminds me of this Scripture, especially the latter part of the verse:

"It isn’t good to have zeal without knowledge, nor being hasty with one’s feet and missing the way." -- Proverbs 19:2 WEB

A well written but inaccurate document is completely useless and should be tossed in the trash. A useful document has both accurate information and simple writing to clearly explain it.

How Do We QA a Document?

To QA a document, just walkthrough the document to verify what it says matches what the product actually does. When it doesn't, then fix the language or pictures until you go to the end.

If you feel it's too daunting to go through the entire document in one go, then you can QA a section after you finished writing and editing it. You can also go through the document in chunks until you're done. It doesn't matter how you do it. What matters is that you QA the document before you release it.

If we take this final, but needed, step then we won't miss our way.  If someone is preventing you from taking this step, push back if you can and tell them to wait until you're done. (Of course, the product and its documentation should go out the same time.)

It's better to take our time and put out documentation at a reasonable time, then rush it out the door and you'll have to deal with a bunch of problems after.

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?

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.

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.

Salmagundi within Documentation

According to Meriam Webster, Salmagundi is:

1. A salad plate of chopped meats, anchovies, eggs, and vegetables arranged in rows for contrast and dressed with a salad dressing

2. a heterogeneous mixture : POTPOURRI

Salmagundi is also a name of various publications throughout the years. But I don't want to turn this post into a salmagundi. So, I digress.

While salmagundi might be a tasty dish, it doesn't taste good in documentation. Unfortunately, salmagundis are a common problem within documentation. Salmagundis obscure, confuse, and can lose the reader. They're bad, especially when your reader needs to learn critical information. What do I mean by salmagundis in documentation?

It's when documentation goes onto over-technical tangents or tries to cram too much information into one document, especially if it's irrelevant information. So much so, you end up with a technical word salad. But sadly, this is the state of much technical documentation out there. I can't count how many times I've seen this be the case. So how do we avoid creating technical documentation salmagundi? Here are some tips. They're not exhaustive but they should help.

Know Your Audience

This is the key to start your documentation. If you know your audience, you'll know how much information to include, how much to leave out, and what kind of information you need to write.

Know What You're Documenting in 1 Sentence

If you understand what you're documenting, this makes a big difference. If you can sum up what you're documenting in one sentence, you'll know where to go. For example, if I said "I'm writing about how to make coffee," then this will direct what steps or information that I need to write. 

Focus the Documentation

If you focus on what you're documenting, this reduces the chances of it becoming a technical word salad. You'll know what points you want to write about. For example, if I were to create a user manual on how to run coffee maker, I'm only going to show you on how to run the coffee maker. I'll include some troubleshooting tips. I might even include the suggested amount of coffee for each scoop to put into a filter. But nothing beyond that. If we don't focus our documentation, we'll get lost in our writing. And that won't be helpful to anyone.

Leave Out Irrelevant Information

This is an extension to the previous point. But it's worth noting. When you write a document, you need to leave out the irrelevant information. You can overwrite by including every tidbit of information about something. But you risk confusing your readers, especially if the information is irrelevant. 

Back to the coffee maker example, I'm not going to mention how the coffee maker was made or what kind of roast would be best. Or even, how to store your coffee. All these points are irrelevant on how to use the machine. You only need to know how to run the coffee maker. Anything else confuses audience or distract from you need to know. 

There will never be an end to the information you can bring up. But a lot of it is neither relevant nor helpful to your reader. So if strays from the point of the document, leave it out! Once you finish writing the document, look through it again and cut what irrelevant information that remains.

I love what Mark Twain once said about books. And I believe it applies to documentation. Twain said:

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

Consider Multiple Documents

Now there are times when you need to cover a lot of information. Just listing steps to your reader might not give them the whole picture about a product or service. If you run into this situation, then consider writing multiple documents. 

So if someone goes through the steps to run a coffee maker but needs to know to grind coffee beans and store them, then write two other documents. One is how to grind the coffee beans. The other would be best practices to store the coffee beans. Breaking down in smaller, more focused chucks goes a long way.

Especially now, when a lot of documentation is digital. You can write short documents and hyperlink them to each other. So, if a reader needs to find further information, they can go to the document that's relevant to them instead of thumbing or scrolling through one big document to find it. 

When I first started technical writing, we would jam as much information as we could into one document. We would sometimes break it into a couple of volumes. But we were doing this because of printing costs. But now, creating digital documents is a fraction of that cost. Sometimes, you can create digital documentation for free. So, there's no excuse to jam everything into one huge document, especially if you only write digital documents. So break up the documentation into easily, digestible information. 

These tips should help keep the documentation focused like a themed dish instead of a salmagundi. It won't be perfect because no documentation is. But, it should go a long way. Keep on writing.

We'll Hang up Our Pens Someday

Recently, Pat Buchanan said he was retiring his long running column. This blog is beyond the scope of politics, so I'm not interested in discussing Pat's stances one way or the other. I'm interested in this angle: We writers, regardless of our stripes, will someday hung up our pens. 

We will someday write the last book, last blog, last technical documentation, the last copy, the last whatever we do. We will all someday write our last word. 

If you say, I'm not hanging up my pen ever, well you don't have a choice. There might come a day where you're no longer able to write or you'll draw your last breath. In any case, you'll be hanging up your pen.

The reality is our writing pursuits and career have an expiration date. But we don't have to dread this impending end. If anything, it should give us more focus to write, since we only have so much time. One thing we can stop because it's an emotional waste of time is self-wallowing. You never be good as any other writer because you can't. All of us are different. Comparing each other doesn't go anywhere. So, don't do it! Also, if you keep talking about writing but don't write, then you need to make a decision. Is writing important to you? If so, write. If not, move on to something else. Writing isn't a glamorous pursuit. It's a hard road. To me, for now, it's worth it.

Finally, when we write we need to decide why we are writing. What's our focus and why. What's your passion? For me, I like technical writing because I like to help others and I want to bring glory to God through it. I'm planning to do this until God calls me to do otherwise, He returns, or I draw my last breath. While I still can, I want create the best documentation that I know how. 

So, write while you still can and know why you do it. We'll all have to hung up our pens, so make it count. 

Technical Writing Isn't Boring

I once saw a movie where an editor insulted a writer over her manuscript for a book and said she needed to write user manuals. I was incensed when I saw that and jeered at the editor. (Maybe I'm exaggerating but I did say "excuse me?" at the character.) 

It's funny because that actually happened to me in a previous writing life as a journalist, where an editor told me that I was better off as a technical writer.

Whether it's in movies or in real life, there seems to be a sentiment that technical writing is boring. It's sleepy. It's dull. It's lifeless. Really?! 

How's it boring when you get a chance to always learn something new, whether it's entirely new product or an update? How's it boring when you can get a chance to write for different industries or subjects? One of the benefits of technical writing is you can always expand your knowledge base.  Boring is if your mind is stagnant.

How's it boring that you get help people through your writing? You can get a sense of fulfillment knowing that you helped someone accomplish a new task. 

If you write documentation just right, it can be like one of those videogame walkthroughs. The genius of a walkthrough is that you get to go on a journey through the videogame and the purpose is that you help someone through the game. It's the same with documentation, just without the commentary or shouting. Taking someone on a journey explaining a product or service might be draining but not boring. Boring is just remaining on Step 1. Technical writing takes steps 1,2,3, and beyond till the end.

How's it boring when you can meet different Subject Matter Experts (SMEs) to help you get the technical information you need to write the documentation? Boring is when you completely rely on own imagination, thoughts, and view. Your writing can get pretty stale, pretty fast, so it becomes boring. 

I met SMEs from across the globe and from all walks of life. Their takes on things and their knowledge has always helped me. The documentation usually turns out better than I could imagine, even if I couldn't see it at the time I was creating a document. Why? Collaboration is what can give technical writing life. 

And if you write in active voice and clear and concise prose, it's anything but lifeless. Passive voice and verbose sentences are the bane of technical writing. They not only confuse and muddle but are lethargic and vapid. So we need inject the syntax with active, concise language to bring life to documentation. 

Clear information isn't boring. Boring is stuffy text, pontificating or rambling on to whatever it was about. And you get lost what we're reading, or in my case, you just fall asleep.

Writing documentation like a flowing river won't put your reader or you to sleep like a meandering creek might. 

Well, maybe a white paper on some theoretical concepts might put me sleep. But for others this keeps them up all night. You can have white papers that are engaging reads.

Technical writing can be hard, frustrating, draining. Boring? Don't think so.