Great Technical Writing Series


 

Home | Contact | Site Map

Navigation:  Home -> Reading Room -> Great Tech Writing Series -> This Article


Content is King 

We've lost sight of the two most important aspects of our User Documents. This loss of focus causes our organizations loss of money and business.

Here is an example from the description of XML from Wikipedia…. I removed the XML to show you only the Content (you can see the original, here: http://en.wikipedia.org/w/index.php?title=Extensible_Markup_Language&oldid=63466304 )

Basic bread

Preparation time: 5 minutes; cooking time: 3 hours

Ingredients:

  3 cups Flour

  0.25 ounce Yeast

  1.5 cups warm Water

  1 teaspoon Salt

Instructions

    Mix all ingredients together, and knead thoroughly.

    Cover with a cloth, and leave for one hour in warm room.

    Knead again, place in a tin, and then bake in the oven.

 

LOOK…LOOK even though it is just an example, they left out a CRITICAL piece of information…the TEMPERATURE to bake the bread.

In addition, they were unclear regarding the baking ("cooking") time. Does that time include the time that the bread is left " for one hour in warm room"?

These are symptoms of what's happening in our industry. We are becoming focused on the technological marvels (XML, for example) and ignore the Content we need to write to satisfy our Readers.

Is that happening to your writing? Are you getting hung up with the XML and all of the other Content Management goodies and forgetting about the CONTENT?

This Wikipedia example is not the only one.

Someone gave a talk at the Eastern Ontario chapter of the Society for Technical Communications (STC). They were extolling the virtues of XML and how they processed it using the language XSLT. However the content that they presented couldn't explain anything to anyone who didn't know the material beforehand.

Often at our STC presentations, the audience asks more about the software than they ask about the methods used to produce the content.

And here's another:

If you bother to visit: http://www.travellady.com/ARTICLES/article-shoppingstroll.html you will see that the author is cute to recommend that you stroll from west to east along Notre-Dame Street, "a la Montrealaise." Unfortunately, the author neglects to tell you where to start walking on Notre-Dame Street.  Thus the author leaves out an important piece of information: where to start (all we needed to know was the cross street). The author left a hole for the reader to fall into.

Perhaps every writer knows how to produce great content. I don't think so.

Have you seen slickly published User Documents that were missing the content that you needed in order to use the products? Most of us have.

Take weak content and package it beautifully (and flexibly, using XML) and it's still weak content. And it will disappoint your Readers.

And a disappointed Reader costs your organization 

The bottom line: CONTENT is most important.

Second most important is making that content accessible to your reader. "Accessible" means being able to find what he/she needs and easily skip over what they do not need at the time.

All of the behind-the-scenes stuff (XML, Content Management systems) is mostly of benefit to you and your organization.

Do not lose sight of the importance of the content that your readers need. And make that content accessible to your readers.

Do These:

 


Resources

Barry Millman, Ph.D., has a Bachelor of Science in Electrical Engineering (1966, Carnegie Institute of Technology) and an M.Sc. and Ph.D. in Psychology (Human Information Processing, University of Calgary).  He has been a consultant for over 25 years, an instructor, course developer, and award-winning speaker.  For the past seven years he has been researching and creating resources to help organizations create great User Documents. 

Visit: http://www.greatuserdocs.com/ for resources to help you create the User Documents that your Product needs and your Users deserve.

Visit http://www.greatuserdocs.com/ReadingRoom.htm for more articles like this one.

You may copy and distribute this article freely.  However you must keep the entire article and Resources sections intact, with no changes, additions, or deletions.

Copyright © 2007, Igetitnow! Training, Inc.