Three Tips for Content Consistency

A common denominator among all content audiences is that they like to latch on to something familiar. It’s our job as content creators to provide a place for our audience to live and thrive. Aristotle said, “We are what we repeatedly do,” and that sentiment sets the frame for defining the needs of all audiences, and the consistency we must provide for them.

It’s easy to be consistent, and here are three ways you can provide consistency for your readers.

  1. From page to page, section to section, create a common look and feel for every document you create. This is done by choosing a format for fonts, graphics, tables, etc., and sticking with it throughout the entire document. Consider creating master pages with headers and footers to provide a uniform look for every page.
  2. Use a like manner in the way information is presented. For example, if a flowchart is used for one process, use it in a similar way for all processes.
  3. Use like names for things throughout the entire document. For example, if the term “module” is used in one section, use only “module” to describe it elsewhere. Having trouble deciding how to name something? Let the manufacturer/inventor decide for you, and carry over their term to your documentation.

As technical writers. we must master the mantra “one meaning per word, and one word per meaning.” Complex documents can be made more complex with inconsistent word usage and meaning. There are constant barriers to reader understanding, and consistency is one way to ensure we are conveying the messages we intend.

Without Structured Authoring, You May Be Working Too Hard

computer-desk-email-7112

It’s the old adage – don’t work harder, work smarter.  This especially applies to content developers.

With the endless demand of taking products to market that meet specific needs of the customer, there’s never been more of a demand for documentation that helps the customer solve problems, save time and prevent operations downtime.  I’ve never met a product developer that wants to be a wrench in the works; and let’s face it, documentation in some form is almost always part of the overall deliverable.

The fact of the matter is technical documentation content creators don’t start from scratch every time.  If you’re currently doing this, read on!

To keep from re-inventing the content wheel each time with every new document, here are a few tips to break free of old thinking:

  • Think about what written content already exists, and plan around what you already have.
  • Your documentation isn’t your own (it’s the company’s property), and it doesn’t need restated different ways to convey the same message.
  • Re-stating the same message different ways isn’t uniqueness – it’s duplication.
  • With good content planning, you’ll see the advantages of content re-use.

If you are re-using a lot of content, structured authoring can provide:

  • Content in small re-usable chunks called topics
  • Less of a need for edits because smaller topics often require less maintenance
  • A depository of pre-prepared content, which is an organizational asset
  • A design to the content (structure) that is built around a planned model

There are concrete reasons why structured authoring is better than a simple cut and paste into a word processing document:

  1. Your organization may have plans for documentation beyond the writer’s expectation. Remember that it’s not the writer that determines how the content is used long term.  Content developers should ready themselves to provide a content management system that can piece together documentation as the organization’s needs evolve.
  2. Remember that every piece of content exists within a reusable context. Messages are built by associating contexts.  These are the building blocks of relevant documentation.
  3. Structured content is sharable among work groups and others both within – and outside – the organization. It creates an easy to use, common format.

Best of all, stored content is searchable and can be recalled easily.  By recalling re-authored content, writers can use topics like building blocks to create documentation.  Perhaps the greatest contribution any employee can provide an organization is efficiency, and structured authoring offers us that opportunity.

Five Reasons Why Software Developers Need Technical Writers

signs-not-to-be-a-programmer-miserable

It’s no small wonder why such a large percentage of employers offering opportunities for technical writers are in the software industry.  The apparent need for more clear, concise and generally better quality documentation has always been good news for technical communicators.  We’re here to do what developers have historically shown they struggle to do well.

Here are several reasons why developers need technical writers to improve their documentation

  1. Developers hate technical documentation because it’s not in their wheelhouse

Developers often feel their writing skills are limited because their work isn’t centered around written communication.  Developers don’t need to center their focus around the needs of a document’s audience, they need to foremost focus on the needs of the software end user and the practical function of the product.

  1. It’s an added responsibility

Developers have to answer for a lot – most importantly, the usefulness of their code.  Quality documentation – presented in a logical, planned format – is not their primary concern.  Often this sharing of responsibility with a documentation professional is a welcome relief.

  1. Code Changes Too Frequently

Developers writing documentation once is a Utopian idea, but not realistic.  Good documentation incorporates frequent updates, and it is more accommodating for developers to feed information to writers than to process it into the documentation.

  1. The push is on

The customer pushes the company, the company pushes the department and the department pushes the developer.   With a due date constantly looming, developers constantly need more time for coding, and less time for documentation.

  1. Developers are Living Inside their Code

Developers are often occupied with the product’s function, and less concerned with the need to explain things clearly.  Fortunately, technical writers have spent years honing skills and techniques needed to create usable content.

Believing developers are most suited for creating technical documentation is a short-sighted view.  Customers will always need documentation with product delivery, and are best served by documentation created by people best suited for the job.  I’ve seen instances where developers waited until the last minute to produce accompanying documentation, and the results were disastrous, usability was low and the end product quality was affected.  Remember – there is always a chance customers will return the product because of poor documentation.  Is there any doubt the skills of a technical writer are part of the solution?

School Days Coming to a Close

graduation-traditions (1)

In a few weeks, I will complete my graduate studies in the professional writing program at Washington & Jefferson, and earn my master’s degree.  It’s a time of reflection for me, and although I’ve never been qualified enough to give a valedictory address, I’m going to take this opportunity to offer a brief and abbreviated one.

In this world of instant information, I believe there’s never been a greater need for good writing.  The power of the written word extends beyond whatever relevance the content delivers, and includes the writer’s ability to listen, evaluate, analyze and critically examine.  Graduate study has helped me learn to hone all of these skills and abilities, and as a result I now approach my writing in a different way than I did when I began the program in July 2016.

My classmates, we will soon join a workforce where fast messaging, instant accountability and diverse audiences rule the day.  We’ve spent long hours studying ethics, the impact of social media and the effects of visual messaging.  These discussions have prepared us to enter a fast paced world.  Fortunately, the skills we have gained will give us an advantage, and prepare us for what’s immediately to come.

That’s not to say that the writing life won’t bring unanticipated changes.  The needs of our audiences are always evolving, but skilled communicators will always be in demand.  So, as we move forward with our professional lives, take opportunities to toot your own horn and share with others what you know and how it can enhance their endeavors.  I can assure you that I will always have a prayer of support for you, and a wonder of what further success and happiness you have achieved.

I want to express my full gratitude to my classmates, Andrew, Kelly, Erin, Lauren and Shannon, whose dedication to hard work and full engagement have helped make my graduate school success possible.  My professors have been an inspiration as well, so I owe further gratitude to Dr. Sam Fee, Dr. David Clark, Eileen Garrod, Jesse Krueger, Steve Halvonik, Dr. Amanda Boehm and Jenna Wandrisco-Truschel.  Finally, a special thank you to Dr. Kathleen McEvoy, our program director who has been the glue that’s held the program together, and who championed this program from the start.  Your kind support and constant encouragement will always be remembered.   Most of all, thanks to my wife Linda and my parents, who sacrificed what were sometimes seemingly unending hours of family time so that I could pursue my dream.

A Checklist for Couples Working From Home

office workers

As employers are adapting to the ever-changing digital world and office space is limited as a result of corporate growth, more writers are working from home.  When more than one person in a household is faced with the challenges of setting up a home office at the same time, co-habitants need a strategy to keep from driving each other crazy.

Couples who have successfully learned to work this way agree some level of compromise should be a precursor to actually setting up office.  Life is full of unexpected circumstances, and it’s going to be impossible to report to the same section of the house, at the same time, daily.  Each partner should understand the other will need a change of scenery sometimes.

Before taking on professional co-habitation, couples should consider the following checklist:

  1. Even though occasional work space variety is healthy, couples should develop a household plan for office space and hours.  Ideally, this should involve a minimum requirement of a wall between work spaces.
  2. Each should have a separate phone line. Fighting over a single land line (yes, these still exist) can be troublesome.
  3. Run a bandwidth check to ensure both can have adequate high speed internet performance when online at the same time. Agree on eliminating, or at the very least limiting, non-work-related streaming during office hours.
  4. Hold state of the household meetings weekly to ensure co-habitation is working. Issues will fester if the other is unware of something bothersome.
  5. Consider a coffee shop work run once in a while, especially when the other has a Skype meeting or phone conference. Consider the value of the other person’s space during these times.
  6. When phone conferencing with others in a different time zone in the middle of the night, consider moving far away from anyone sleeping. Lack of sleep causes irritability and limited patience.
  7. When the work day is over, enjoy quality time that meets the needs of both. Couples who practice work space separation during the business day seem to appreciate quality time after work more.

Be reassured that negotiating a shared living and professional workspace can be done, and can be enjoyable.  However, a few basic rules of living together in general still apply.  Try to refrain from criticizing the other’s work habits, keep your work stresses separate, and communicate about non-work related household issues like you would if you were still commuting daily.

The above checklist are general guidelines, but because every relationship is different, they may not work for every couple.  Give ‘em a try and see what works for you!

Working with Content Management Systems

Here’s a very well thought-out summary about working with content management systems (CMS) presented by STC’s Technical Communications Body of Knowledge (TCBOK).  Although ideas differ among organizations about what constitutes a content repository, the ultimate goal is having topics that can be used for different purposes.  Author Lauren McCarthy of Appalachian State University presents a great overview about why CMS is important in the field of technical communication.  This article should be helpful in determining which use meets your needs.