Error Messages: Best Practices for Supportable Product Development

By Samartha Vashishtha
Senior Content and Community Lead, Adobe Systems

While functionality deservedly remains the primary focus in the development of any software product, it’s also important to ensure that the product is easily supportable. Error messages – being the first line of support for a product – contribute significantly to product quality and the customer experience that it delivers. Poor error messages that are “plugged in” as an afterthought towards the end of the product lifecycle lead to frustrated customers, avoidable support costs, and loss of corporate goodwill.

Structural foundations of a good error message

A good error message is direct, short, and communicates just the right amount of information. When you write or review error messages, attempt to cover answers to the following questions:

  • Is the message an error, warning, question, or a piece of information for the user? The error message could begin with labels like Error: or Warning:
  • What exactly is the error? For example, Error: Could not write to the disk …
  • If the message is an error or a warning, the message should clearly capture what went Error: Could not write to the disk because it is full.
  • What is the solution/workaround? If no workaround is available, request users to contact the Customer Support Organization. Error: Could not write to the disk because it is full. Delete some files and try again.

Additionally, every error message should have a unique alphanumeric error code that customers can quote when they call customer service for support. These error codes also come in handy when customers are searching for troubleshooting information on the Web. In fact, content strategists often metatag troubleshooting documentation and technical notes with error codes as an SEO measure.

Wherever possible, error codes should be duly displayed in dialog boxes, especially for enterprise products for which customers have priority access to customer support. These messages could be unobtrusively displayed in a collapsible panel or a smaller font variation. For example:

error message png

Wording error messages

In an ideal world, error messages need to be a shared responsibility of product engineering, technical communication, content strategy, and User Experience Design (XD) teams. However, owing to timeline constraints and the fact that error messages are often treated just as a checklist activity, developers often end up writing error messages without much review support. Wordsmithing assistance is often sought late in the cycle and only for identified “problematic” error messages.

While writing error messages, developers/testing engineers can consider the following writing guidelines:

  • Use short sentences; 15 words at the maximum. Limit the error message to a maximum of 2-3 sentences.
  • Keep the sentences friendly, actionable, and conversational. Avoid a patronizing or reprimanding tone. Transfer the blame on the software rather than the user.
  • Avoid negative words like abort, catastrophic failure, execute, human error, etc. A typical example of a negative error message is the infamous DOS “Bad command or file name” message.
  • Avoid using programming jargon. However, it’s OK to use the necessary terms if the error message is intended for a predominantly developer audience.
  • Avoid over-communication. Unless absolutely necessary, do not include technical details about the error. Users are most interested in resolving the error as soon as possible and carrying on with their work.

blue screen

Over-communicated jargon: The Blue Screen of Death (BSoD)

  • Get the error message peer/buddy-reviewed. Involve your content strategy counterpart in the review process, whenever required.

Looking ahead…

The following suggested process improvements would facilitate the creation of useful error messages:

  • For easier review and localization, separate error message content from functionality code. Instead of hard-coding error messages, display error messages by reference.
  • Error messages should be part of the “Done” definition for agile sprints and significant milestones. If that is not feasible, error messages should at least be part of sprint backlog items.
  • Error message review should be part of buddy code reviews as well as quality reviews.
  • Review support from the content team should be enlisted earlier in the cycle, especially for priority components that significantly impact user experience

While tracking error messages as part of the overall program plan might seem like an initial overhead, benefits realized in terms of customer loyalty, reduced support call volumes, and fewer “reactive” fixes far outweigh the efforts.

Posted in Uncategorized

Content strategy has two aspects, but which is the most important?


By Steven Grindlay

I’ve heard content described more than once as the stuff of communication. I agree. It makes good sense. If not content then what else would communication be constructed from? If we accept this as true, then it must also be true that wherever there is communication there must also be content

OK , so let’s agree then,

Content is the stuff of communication.  Strategy on the other hand, is the thinking and planning with the intention to shift or reposition something from a present condition or state to a more desirable future state.

Taken together, we could say that content strategy means:

  1. The use of content to create a strategy that shifts the organization’s communication from a present state to a more desirable future state.


  1. A strategy to shift content from a present state, to a more desirable future state.

In fact, content strategy is both.

Both are vital; they are the different yet complimentary sides of the same coin, the two wings of the same bird. If either are neglected our content strategy is pointless and it will fail.

At first glance the difference seems subtle, but they’re really worlds apart.

The first meaning is about strategic intent.  How can content strategy help companies become or remain more competitive, who should they be talking to, what should they be saying and what results can they hope to expect?

The second one is about an executional strategy and managing the content life-cycle. Things like:  assessing the content we have, deciding what content we need and how will we create it; how, when and where do we publish and promote it, measure its success; and finally, when do we retire it?

We content strategists are often guilty of overemphasizing the executional strategy of CS,  becoming  a bit too fascinated with our process, tools and templates. Often at the expense of the bigger picture.

At times it’s a bit like watching a group of craftsmen having an animated discussion about how wonderful their tools are. One claims his hammer is better than someone else’s, another insists they have the better measuring stick. Pointless debates arise about who’s the better bricklayer, carpenter, foreman etc. Completely lost from sight, is the original purpose. Building the Taj Mahal.

The building is impressive.
The tools are not, the debate even less so.

Nonetheless the tools are essential. The processes of content strategy the nitty-gritty details that get it done and put it in front of the intended viewers’ eyes shouldn’t be underestimated.  After all no matter how compelling  the vision, you can’t travel to the moon if you don’t know how to build and fly a rocket ship.

I believe we’re past that point we’ve nailed the rocket science completely. I think the problem facing content strategy today, is not finding a better template, a new tool or process for executing procedures. The really thorny issue is how we’re going to initiate a conversation in boardrooms and the executive suites of big business —or even, not-so-big business?  What are we planning to say to them and why would they want to listen? What problems are we solving?

What compelling message is it that content strategists need to deliver to get business managers to sit up and pay attention? I’m not talking about a slick, roll-off-the-tongue content strategy definition here; I’m talking about how organizational conversations can be shaped to meet objectives.

Business management want to be impressed. They’re looking for content strategists to show them a vision, to step up and identify and lead a strategic initiative that helps them solve difficult problems in a complicated business environment.  They want to know what to say and whether it’s worth saying, and who to say it to. They want a compelling story, the majestic palaces, and the vision to become real. They want to shine.

And they want it delivered in an executable, effective, measurable, cost-efficient plan that elevates, distinguishes and differentiates their organizations and its products in the minds, hearts and wallets of the marketplace.

In my opinion, that’s our job.



As usual the thoughts and opinions are mine and mine alone and they do not necessarily reflect the views of the Content Strategy Alliance.

Image Credit: The god Janus on a Roman coin. Public domain

Posted in Uncategorized

The Content Creation Guide: Making Copywriters’ Lives Easier

By Noreen Compton

There are a lot of templates on the web to aid in the content strategy process. What I often see overlooked is a template for the content strategist to turn over  to copywriters that has all the accumulated information they need to write the content.

While I have seen a version of this (with less emphasis on the messaging)  called a “Content Template,” I have called my document a “Content Creation Guide”  to distinguish it from CMS templates.

The content strategist has hopefully been active during all the phases of the content process and been privy to all the marketing and UX decisions that were made, as well as the research. The Content Creation Guide provides all the relevant info about content that has been identified for each page.

It can include: description of the page content, audience, primary message, key phrases, keywords, source content, word count and sample content. This has been used in ad agencies with digital arms and less so in digital agencies, probably because ad agencies focus more on the messaging in general.

Below is a link to the  template I use and an example of a filled-out template.

A copywriter told me that this Guide made her 110% happier and 90% more efficient.

What are your thoughts?



Posted in Uncategorized

What Content Strategist Don’t Like About their Role

By Noreen Compton

In the 2014 Content Strategy Survey, we asked, naively:

If you could change one aspect of your current role, what would it be?

We got 579 answers. They are summarized below.

How would you answer the question? Are you surprised by these answers?


  • Executive leaderships investment & appreciation
  • Support and recognition of all stakeholders.
  • To get more support for the many different roles I am required to play.
  • We need professional associations who can offer further education.
  • Make it a proper job
  • Organizational acceptance and larger budget allocations.
  • To not have my role be a second thought, i.e., to be thought of as integral as a developer or project manager (who are usually the ones who insist on bringing me into a job).
  • Hire real content strategists to do this work
  • Get CS more involved up front; don’t wait until the site has been designed and then ask us to come in and “deal with the content stuff”
  • Having clients actually do what we recommend
  • For those at the highest levels to understand that we are problem solvers – that there is more to content than copy and paste!
  • I wish we could have more of a long-term impact on our clients’ content strategy and implementation of our work.
  • Have the power to fully implement policies related to content (in the very broad sense) creation and management
  • More outside support for technical questions aimed at librarians (subject specialties


  • Better recognition of this as a discipline. Although that is likely our (my) fault.
  • More definition around the content strategy discipline and where it fits into the overall digital process.
  • Having best practices to use for my job
  • Change in title to more accurately portray what I do.
  • More clearly defined roles within the project team.
  • I need my job description and title to reflect content strategy – right now I’m severely underpaid and valued as simply a “writer.” I do so much more than that, and want to as well!
  • I would like my seniors / bosses to have a better understanding of my role than they currently do. They need training as well!
  • Make the IT department and corporation understand that a website is a communication tool, not a file repository
  • More understanding of the role of a content strategist throughout my organization
  • More transparency between myself and the client, in regards to my role and responsibilities.
  • Having an in-house mentor. No one else here does what I do, and so I’m generally in the dark about what I need to be doing. It’s hard to know what I don’t know.
  • Making people more aware that good upstream content strategy means better product downstream


  • More strategy, less execution.
  • More time from my team to work on moving forward our Content Strategy Roadmap, rather than tactical, release work.
  • Spend more time for big-picture analysis/strategy, less time down in the weeds
  • Strategic impact


  • Focus less on content for our product and focus more on marketing and sales collateral creation.
  • More autonomy.
  • More power in overall marketing and business strateg
  • Over-emphasis on marketing to the detriment of a beneficial user experience and strong brand consistency.
  • Spend more time doing content marketing


  • Currently my position influences multichannel development, but it is primarily Digital — would like to evolve role to have greater influence on development of non-digital as well as core digital channels
  • More digital
  • More multi-channel


  • More time to get the work completed properly
  • Better pay
  • To focus more on some specific aspects rather than being spread so thin across many roles.
  • Hire more people to help.
  • More time and money for the creative process.
  • Bigger budgets!
  • Spend more time producing content relevant to the users, and less time producing/maintaining useless content just because it is contractually obligated.
  • I manage our Content Strategist. She is pulled in many directions so I’d love to get all other responsibilities off of her plate.
  • More time for planning
  • More organization around me!
  • A way to keep myself better organized


  • I would work as an regular employee for the company, rather than as a contractor employed to fix a long standing problem – content management is an ongoing role, not a one and done task.
  • Have the ability to work directly with clients rather than through an agency.
  • More gigs
  • More consulting clients. I enjoy strategizing and guiding clients with their content


  • If I could lessen the territorial nature of content-related disputes, that would be great.
  • Greater recognition for content strategists who focus on editorial content. The “Digital” group thinks they own and invented everything.
  • Not having to fight to get others to let me do my job effectively.
  • Integration with wider agency & other teams
  • Have a content manager who worked for me and policed/implemented the governance
  • Work closer with design & UX
  • Project teams aren’t very welcoming. They don’t understand the role and feel that it infringes on their responsibilities


  • More cheddar.
  • More stable platforms to work on ;)
  • Less stress
  • Variety of work – more than one project
  • I’m currently straddling the line between my old career – UX – and my new one – CS. My firm has me working alternately in each, but it might be nice to have more CS work.
  • To simplify it!
  • More focus on content security
  • Less focus on content as an output, more as a design input.
  • Lessen the influence of developers in the content modeling and work process. It’s not a product for dev teams; CS has a much broader focus.
  • Better integration with technical areas where content is generated
  • More experience / time spend in the production of content.
  • Dislike that content strategy is getting separated from UX and pushed over to CMS
  • To improve the ease of clients finding the information they need
  • Increased influence over platforms and global process
  • Streamline process for content approval
  • Greater value and appreciation for original content creation
  • The poor (not fit for purpose) CMS
  • Better selling of content by sales
  • More input on the UX and design fronts.
  • I would spend less time writing social media messages and more time

measuring and doing strategy/analytics.

  • Greater influence on product development
  • Customer’s perception about my work worthiness
  • Restrictions on software by corporation
  • Like to have control over the CMS and not have to accept so often that “The CMS can’t do that,” when I suspect it can.
  • Find more repeatable business
  • Continue to push for a voice in the Creative process. I have just joined a new agency to build out their CS practice and our Creatives are very new to the idea.


(Some people are living the dream…)

  • None
  • Nothing.
  • Nothing. I love my job and team.
  • Nothing! I work for myself and love it. Worked hard to make it happen.
  • Not a thing. I’m new in this role (about 5 months) and I’m absolutely loving it. It’s my first true pure content strategy role – very little writing, pretty much all CS.









Posted in Uncategorized

Is the title of Content Strategist important? Or just the work?

By Noreen Compton

In the 2014 Content Strategy Survey Report, we noted that 90.5 percent of respondents reported doing content strategy work, but 61.7 percent said that their employer does not have a role titled “Content Strategist.”  We suggested this indicates a lack of understanding about content strategy within organizations.

And Firehead wrote on their blog last year:

Firehead noted that 7800 people were listed as content strategists on LinkedIn in July of 2013. But many more listed content strategy on their LinkedIn profile. They pondered the reasons: do some countries call a content strategist something else? Or maybe other roles include content-strategy-related work but use a different title?

With suggestions having been made elsewhere that Information Architects and Project Managers might be the “new Content Strategists,” is the title of “Content Strategist” important? Or is it just the work? Interested in your thoughts.

Follow the discussion on the LinkedIn Northwestern MOOC board:

Posted in Uncategorized

Fun Facts From the 2014 Content Strategy Report

By Noreen Compton

We have a lot of stats from our survey.

  • Do you have any thoughts on what some of them mean and how they are significant?
  • Were you surprised by anything in the survey?

We are interested in your thoughts.

  • Primary areas of expertise (you could pick more than one): Strategy 70.9, Editorial 65.8, Marketing 55.8, UX 54.5, IA 47.4%, Media/Publishing 40.9%, Technology 29.3, Governance 27%, Taxonomy 26%, DITA 4.9%
  • 90.5% of responders report they are doing content strategy work but 61.7% said their employer doesn’t use the title of content strategist
  • Regardless of experience, 80.8% of responders said they are self-taught in content strategy
  • 64% of responders are employees; 35.4% are independent contractors or consultants
  • 24.8% of responders have 2-3 years of  experience;  more than half 6 or more years; 22.4% have 10 years or more; 8.9% of respondents have been doing content strategy for more than 15 years
  • 36.9% of responders work for corporations; 46.4 at ad agencies, content or digital consultancies
  • 12.6% of responders work for a content strategy consultancy
  • Top  tasks reported: content assessments 73%; editing 71.4%; copywriting 62.9%; analytics 57.1%
  • 36.1% of responders said they work on wireframes
  • 55.3% of respondents do digital work only; 44.7% cover multi-channels
  • 39.3% reported lack of credibility inside organizations as their biggest challenge
Posted in Uncategorized