Need for single sourcing

I heard a true-life story recently about a technical writer who was hired for the sole purpose of updating a company’s name and address in all the technical manuals available through the company website. It took the highly-compensated employee months to find, correct, and proofread every instance, and although declared complete, the project isn’t over yet. New occurrences of the old name are still being found.

In a tight economy, this is, frankly, an expense that should be avoided! A company’s name and address should be stored in one place. Every document published by every department should refer to that single location. Then, when the inevitable happens and the company changes names, a simple update to a single file would save hours of searching, changing and proof reading.

Sounds easy, right? Implementation of such a system is far from easy, mainly because departments own their content and are either unwilling to share or have good reasons why they cannot share, and because proprietary publishing tools are incompatible. Even within a tech pubs group, the wheel gets reinvented as each author writes and rewrites the same material—at the most copying and pasting from one other.

Content sharing requires an honest commitment to shared goals and a new publishing paradigm.

Commitment: To share goals requires a clear understanding of the benefits for each group. Each must be able to answer the question, “What’s in it for me?” Recognition and rewards need to be structured to promote content sharing.

New paradigm: Instead of collecting information in books, authors and managers need to think in terms of reusable content chunks, which can be treated as objects and assembled from a single source to produce: paper, online help, website content, etc.

This new commitment and paradigm do not need to result in loss of control. Topics need ownership just as much as documents do. Topic review and approval is as important as is document review and approval. Updating responsibility needs to be clearly defined.

Finally, technology must support the goal of shared content. But, technology is but the tool. Commitment and acceptance of the new paradigm are the most important factors to success.

Be the first to rate this post

  • Currently 0/5 Stars.
  • 1
  • 2
  • 3
  • 4
  • 5

Writing for use

More an art than a science, writing useful technical materials requires audience knowledge, imagination and practical experience with a product or service. Technical writers are often required to write about products before the products even exist. Writing "technical fiction" demands an active imagination. What kinds of problems might people encounter? What questions are they likely to ask?

Product engineers know the answers to the basic questions, such as, where is the power switch located? But when called upon to write materials for novice users, they rarely consider the plight of the poor person who has not lived with the product for a year, as they have. Invariaby, engineer writers opine about super-duper features or aspects of the product they themselves find confusing.

Does this describe you? Before you put fingers to keyboard (alias pen to paper) for your next user manual, talk to at least one real user. If you don't have access to a real user, at least do a simple usability test: ask your girlfriend/boyfriend/wife/husband to perform a simple task using your product. Don't coach them. See what problems they encounter. Take notes. Sleep on your findings. The next day you'll have insights you never would have noticed otherwise. Then start writing.

Be the first to rate this post

  • Currently 0/5 Stars.
  • 1
  • 2
  • 3
  • 4
  • 5