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.