Information Architecture Blog Posts
Do you want to share your thoughts and expertise with the community? Post a blog in the Information Architecture group to get the information exchange started.
cancel
Showing results for 
Search instead for 
Did you mean: 
Jordan_Stanchev
Product and Topic Expert
Product and Topic Expert
1,850

There is a breed of writers who can write a whole book in one sitting. They write and write and in two days they produce a whole novel. According to Wikipedia, Stephen King is famous for doing just that.

Great, isn’t it? But it’s not like that in technical writing.

Even though we are referred to as authors, unlike Stephen King’s fans, our readers won’t be delighted to see a bestseller-sized chunk of documentation drop on their desktop. And as technical writers, our goal is not necessarily to keep the reader gripped to the very end so that they read every word we wrote!

Our goal is the exact opposite! We want our readers to spend as little time as possible reading documentation - we want the reader to stay focused on getting their job done.

I’m always amazed that so many technical writers spend most of their time writing, producing endless volumes of content, and adding chapters to already bloated guides.

Can you imagine your readers saying: “Oh, I can't wait to read another chapter about configuring this software. My favorite part is when the connectivity service never manages to find his long-lost brother - the back-end system! And their mother, the service core - does not even know that her long-lost child is still alive. What a gripping read”.

At least in my experience, I have never seen a customer ticket appreciating the volume of the documentation!

But I have seen tickets like: “we know that the configuration we are looking for is documented somewhere, however, we cannot find it at all, as you have too much documentation! Here is a high-priority ticket for you to find it instead of us!”

Uh! That is just embarrassing! 

Take a step back

Look at your content objectively and ask yourself the following questions:

  • Am I writing information that is not needed to solve the problem?
  • Can I use a graphic or a diagram to explain it better?
  • Should I use a video instead of written text to make it faster for the audience to get that concept?
  • Can I break this topic down into smaller self-contained topics that answer only one question at a time?
  • Can I apply minimalism principles in how I say things?
  • Should this be written documentation or embedded information on the screen?

Getting Creative

Alright, alright, for all of you who still see themselves as creative writers and not only as technical writers - what is it that you can do with the creative spark inside of you? My recommendation - write beautiful and fun-to-read blog posts for your customers on your company website - and then link them to your short and straight-to-the-point software documentation!

Over to you!

What do you think? Do you tell stories with your documentation? Do you create tight bursts of targeted communication, or do you find yourself adding to some monster document that has a combined word count larger than the Library of Congress? Have you found a happy medium between storytelling and help documentation? Let us know in the comments!

You can also check out the previous blog posts on this subject:

  1. #1 - Don’t write it like a song! 
  2. #2 Taking the bricks out of structured writing! 

 

5 Comments
Pao
Advisor
Advisor

So true! 

Loved the fun way in which you wrote this. Thanks 🙂

Bob_McGlynn
Product and Topic Expert
Product and Topic Expert

A problem with writing documentation is focusing on the job to be done. When someone comes to review our documentation they aren't doing it for pleasure (as they would a Stephen King book) they have something they need to do. Often, it's just a simple task - how do I run that report? 

What happens is that the topic provides the history of reports, every kind of report available, how you initially configure the report, and creating the distribution list to send out the report. Hidden somewhere between collapsible sections is the 5 step you need to run the report. 

It's not just a novel, it's providing lots more than someone needs for the job to be done. Short, task-oriented instructions to get someone what they need so they can finish it quickly and move on with their life -- like reading a Stephen King novel. 

BettinaS
Product and Topic Expert
Product and Topic Expert

I always say: We don't write for the Pulitzer Prize 😉

Bob_McGlynn
Product and Topic Expert
Product and Topic Expert

It takes a different kind of skill - a clarity of communication and an understand of what the user is trying to accomplish. You have to be able to explain how something works, which takes skill. It's so sad, in some ways, because when you do your job well, it's invisible.

dwightan
Associate
Associate

Love this blog! I agree with everything. About taking a step back, also consider whether the sentence, paragraph, or even the topic is needed at all. As Microsoft says: “The best [documented] step procedure is the one you don’t need.”

On the point of creativity—there’s creativity in almost anything that’s done well. I’ve seen documentation that is a pleasure to read, without getting in the way of its ultimate goal—to be taken for granted (or to be “invisible”, as Bob says). You don’t need metaphors or descriptions of the sky to be creative.