Join the [Technical] Conversation



April 2011

Join the
[Technical] Conversation

 CIDMIconNewsletterAmanda Cross, ExactTarget

Many people I encounter, even very tech savvy people who have active online lives, are shocked and frightened by the notion of making their product’s technical documentation openly available on the Internet and indexable by search engines, let alone trying to incorporate it into the online community. However, the decision to open your documentation can be a strategic one. This article describes why having an open documentation philosophy need not do harm and how it can raise your company’s esteem among the user community and in competitive fields.

Some types of information that your company collects, creates, and maintains in the course of doing business have good reasons to be restricted to customers or employees. When granting public access to a piece of information carries more risk than reward, it’s in the company’s best interest to keep it secret. For example:

  • Content that must be protected by law, such as classified material or information that regards national security
  • Personally identifiable or private information about customers, employees, suppliers, and so on
  • Anything that could identify opportunities to would-be attackers, such as security vulnerabilities in your software
  • Content under trade-secret protection
  • Pricing information, especially if you routinely offer discounts and incentives

Too often, though, businesses don’t weigh the risks and benefits for each information type individually and make a sweeping pronouncement that all information, including product documentation, must be kept secret. Doing so is not in the company’s best interest because it misses the opportunities afforded by openness.

Dispelling the Myths

Before we can talk about the exciting opportunities, we must discuss the arguments against a policy of openness.

Concern #1: Competitors will duplicate the functionality

The most common concern I hear about the openness of documentation is the worry that competitors will be able to reverse engineer the product from the documentation.

Personally, I like how this concern imbues the technical documentation with a mysterious power to educate people not only on what the product does, but also how it was built. What I must reveal to people, though, is that most customer-facing documentation contains three kinds of content about a product:

  • What it is
  • Why you would want to use it
  • How to make it do what you want it to

Most customer-facing documentation, however, does NOT contain these kinds of information:

  • Secrets of how you built these features
  • Instructions for building a competing product
  • Product road map

The topics that are covered are similar to the topics covered in your advertising material, and no one would say magazine ads and television commercials should be kept under lock-and-key. Consider the material differences between the marketing/advertising material and the customer documentation at your company, and ask yourself, “If a competitor had access to this information, would it allow them to reproduce it?” If the answer is no, you might have a good candidate for open documentation.

Concern #2: Competitors will use the information against us

The second-most common concern I hear is the fear that competitors will discover a product’s weaknesses and exploit those weaknesses in discussions with prospects.

What I explain to people with this concern is that hiding your information does not stop your competitors from saying whatever they want about your company and your product during their pitch. Hiding the truth of your own product only forces the prospect to accept the competitor’s assessment of your product. It is to your company’s advantage to ensure that your voice is the one telling the story of your product with complete, professional technical communication.

As we’ll discuss later, the fact that your documentation is open communicates to the marketplace that you’re proud of your product and have confidence in its abilities. Ask yourself, “Does the user documentation tell a complete and honest story about our product that we can be proud of?” If the answer is yes, you might have a good candidate for open documentation.

Concern #3: Hackers will use the information to compromise the system

Clearly this concern does not apply to everyone, but many people working in technology need to prevent access to their systems by attackers.

If you are not familiar with the intricacies of hacking, you may not know where to begin in assessing the risks of opening your content. Fortunately, there are experts who can analyze your data types with you and identify any that should be kept internal. Together you can ask the question, “If hackers had this information, could they get access to privileged or proprietary information which, if compromised through alteration, corruption, loss, misuse, or unauthorized disclosure, could cause serious harm to the organization or individual owning it?” If the answer is no, you might have a good candidate for open documentation.

It Could Be a Moot Point

Most documentation tells the reader no more than the reader could have eventually worked out through trial and error. The main benefit of many products’ documentation is to save the user the effort of going through the same discovery process the writer used to create the documentation.

That being the case, none of the concerns above matter at all if your competitors already have access to your product. If they do, then any competitive advantage gained by secrecy is already lost, and you might as well reap the benefits of openness. If you are not sure if your competitors have access, consider these questions:

  • Could they have hired a former employee of your company?
  • Could they have hired a former client of your company?
  • Could they have won the business of a former client of your company?
  • Could they have family, friends, or associates who work at your company?
  • Could they have an association with a church, charity organization, networking organization, or other extra-curricular group that uses your product?
  • Could they buy your product themselves?

If you come to the conclusion that your competitors have access to your product and, therefore, already know as much about your product as they could learn from your documentation, then hiding the documentation does nothing to deter competitors and everything to deter customers.

And frustrated customers are certainly NOT a competitive advantage.

The Exciting Opportunity

If you’ve established that the risk of opening your customer documentation is acceptable, then we can discuss the rewards that open documentation can offer.

Signaling the Market

If your company is the innovator in the space, then high visibility into your documentation can act as an important market signal. Technology is not a sustainable differentiator anymore. Companies that innovate keep ahead by constantly introducing new technologies that become “table stakes” for competitors to stay in the market. You may introduce innovations fast enough to be a market leader, but your customer base cannot demand them of every player in the space if you don’t spread the word. Indexed documentation is not the only way to do this, but it does help.

If your company is socially responsible, then open documentation is also a market signal. In his article about renewable organizations, Tristan Bishop discusses the characteristics of companies with high and low levels of environmental sustainability. According to Bishop, being highly sustainable is about more than just going paperless; he says the mindset to be sustainable is visible in how the company approaches its technical documentation:

The renewable organization is optimized for long-term growth and the health of all entities involved, including shareholders, employees and customers. For this reason, in the renewable enterprise:

1. Documentation is a proactive
customer care channel.

2. Documentation meets the growing
demand for self-service support.

3. Documentation authors are
respected communications experts.

Because the over-arching goal is to build customer loyalty, documentation authored for the renewable organization:

  • Reflects the state of the product as it
    exists on the day it is READ.
  • Includes knowledge gained through
    actual customer usage.
  • Builds marketplace credibility for the
    product and the brand.

Building the Brand

A theme of the Internet age is transparency. Industry leaders can’t wait to extol the virtues of conducting their business in a transparent way. For some, transparency is difficult from the very beginning. Brian Dunn of Best Buy discussed his difficulty in giving up control of the conversation:

A few years ago our chief marketing officer asked me to get into social media. He was ahead of the curve in realizing that a cultural transformation was happening. Best Buy (BBY) has 180,000 employees, the majority of whom are 24 years old or younger—and so a lot of workers were on MySpace and other sites. I asked him how we could control it, and his answer was: You can’t. You engage with it.2

It gets more difficult, though, when you start talking technical facts. Putting the hard information about your product out for the world to see invites the community to discuss the strengths and weaknesses of your product, and there’s nothing to ensure that what they’re going to have to say is always complimentary.
But there are at least two good reasons to risk the slings and arrows of public critique. First, businesses are increasingly realizing that letting the customer see that you make mistakes and address them appropriately builds a greater level of trust and engagement than if the mistake had never been made. As D. Daniel Ziv explains in his article, “The New ROI: Return on Interaction,” the business assumption that customer support costs should be continuously slashed is proving untrue as the very act of engaging with a customer, even an unhappy one, provides the opportunity to build a relationship that results in real customer loyalty.
3 Consider a recent red-face moment by an employee at the

Red Cross who accidentally sent a message about getting drunk via the Red Cross’s Twitter account that was intended to be a private message to a friend. The Red Cross responded with humor and the mistake ended up resulting in an increase in donations. From “Red Cross Turns Twitter Faux Pas into Boon” on

The incident—or more correctly, the handling of the incident—revealed its human side and managed to bring its constituents closer in a situation that could have alienated them. It even won some new fans.4

The second reason has been touched on before: that your business chooses to remain quiet does not stop others from talking. Jay Baer, president of the social media consultancy, Convince & Convert, defines your brand this way:

Your brand is the sum of all the conversations about it. You can choose to engage in those conversations, and thus possibly impact them, but you can’t control the conversations. Social media doesn’t create positivity or negativity. It just puts a magnifying glass to how people already feel about your company.5

This transparency is a major shift from the notion that marketers control the conversation. Today, marketers are challenged to join the conversation to provide a clear picture and help influence the opinions of the customer—the ones who are really controlling your brand.

Much discussion of marketing and social media might leave you wondering how it relates to technical documentation. Documentation that is open and findable is excellently positioned to provide an expert voice in the online conversation about your brand. In “The Evolution of User Manuals,” MindTouch CEO Aaron Fulkerson, says:

Documentation, once siloed in the realm of how-to guides, is actually feeding top-of-the-funnel activity. In fact, some companies that I have spoken to are reporting that their documentation is bringing in over 50% of their qualified leads. I can report that my company receives 70% plus of our site traffic from organic sources, and our documentation generates more than half of our overall site traffic. Furthermore, over half of our lead generation is driven by our documentation.6

I personally have seen evidence that this is exactly what is happening in my case. Consider this email my team received through the feedback form on a page in the customer-facing documentation:

I am a prospective customer and it is nice to see articles such as this one, especially given the fact that I will need any assistance I can get to help me as I integrate [the product] with CRM.

Documentation Best Practice

Documentation wikis are quickly becoming a standard in online documentation, and many of these wikis are available for customer contributions and employees, if not from anyone in the world. From “User Generated Content: Embracing Social Networking to Deliver More Engaging Technical Documentation”:

The advent of Web 2.0 has reshaped technical documentation. Bringing technical communication to a Web 2.0 space, in which users generate much of the content, has distinct advantages. Content that we develop solely on the basis of what a subject-matter expert (SME) considers to be important features of a business application may be somewhat different from what users perceive as important while actually using the application.7

The fears that people have about information falling into the wrong hands or people vandalizing content are failing to materialize in a way that costs more than the benefits gained by the community building.

Being the Voice of Authority

Your company would be pleased to build a community of product advocates who recommend the product to others. A surprising amount of the time, product advocates blog about procedures they use to do cool things with your product. But people blogging about your product aren’t always fans. Frustrated users who finally figured out how to work around a bug may feel the need to save their fellow users the heartache and write up a nasty-sounding post about it.

Though one of these scenarios sounds positive and the other negative, you can’t lose sight of the fact that in both cases, the customer is dedicated to your product and trying to help
others benefit from it. Nor should you forget that these blog posts are now a part of the online conversation. These customers may love your product, but they’re performing a labor of love to document things that interest them, good or bad. They have neither the tools nor the access nor the incentive to ensure that their information stays complete, correct, and up-to-date.

Should another customer come upon one of these blog posts and fail to implement the procedure because the content is out of date, the reader may not make the distinction between the blogger and your company. More likely, that customer will leave the experience thinking that your documentation is bad, especially if a web search does not turn up an authoritative alternative from your company.

You could try to harass these would-be documentation writers to take down their content, but you’ll be more successful and alienate fewer dedicated customers if you, instead, add your authoritative voice to the conversation.

In “The Wonderful, Horrible Life of User Generated Content,” Ellis Pratt discusses the trend of users coming upon unofficial documentation. Reasons for this phenomenon, he says, include the official documentation not being available enough or of high enough quality. It may also be that the solution being discussed isn’t officially supported by the company or that the user simply happened upon the official version in the course of other online reading and didn’t think to look for something official. Pratt goes on to describe possible solutions:

As there are a number of reasons why the problem may occur, so there are a number of possible solutions.

  • The official user documentation
    needs to be findable via Google. If
    users begin their quest by searching,
    then they are likely to continue to
    use that approach.
  • Present professional user
    documentation and user generated
    content in the same system. If
    they begin by following links, then
    they are likely to continue using
    that approach. If we can guide users
    to professional user documentation,
    with all the version control and
    provenance information it usually
    contains, at the right time, then we
    may be able to combine the best of
    both types of user documentation.
  • Engage with the bloggers via the
    comments to provide links back to
    the official documentation.
  • Consider the search terms users
    might enter and provide information
    that will appear high in the rankings.
    This may involve creating pages on
    topics that are not supported
    officially and contain a number of

Meeting Developer and Online User Needs

If the majority of your end users can figure out the product for themselves, purchase on-site training or service contracts, or only use your product apart from the context of the internet, then a closed approach to documentation availability will probably suffice. However, if your product offering exists online or includes an API or other developer tools, a more open

approach is probably in order.

API users cannot do without extensive reference information and code samples, which
are difficult to convey through training. Plus,
this community is increasingly accustomed to being able to use their internet search engine of choice (not just the search in your help tool) to find answers to their technical questions. Online communities of practice are ingrained in the developer culture, and you risk your esteem as a development partner if you do not provide the resources to support them.

For example, in the blog post “I’m done building Facebook apps for clients,” Ryan Waggoner describes how Facebook’s decision to close down its API documentation wiki has driven him to refuse to write any more Facebook apps for his clients:

Then in April 2010, Facebook decided to completely revamp the platform and roll out a series of new APIs, complete with new methods for authentication and new documentation. They deprecated the wiki and apparently hired the worst technical documentation guy they could find to write the docs.

So I’m done. The money is good and there’s a lot of work, but the stress and frustration just isn’t worth it. Until Facebook decides to implement some controls to stabilize the development of the platform and write some documentation that’s actually semi-useful, I’ll work somewhere else.


No one knows your content better than you do, and only you are in a position to make the decision about whether your content should be openly available. I hope this argument for open documentation has been a thought-starter to help you begin evaluating your information types and making your own case for how an open communication policy can benefit your customers and your company. CIDMIconNewsletter

Cross_AmandaAmanda Cross


Amanda Cross has worked in the field of technical communication, specifically software documentation, for over ten years. At ExactTarget her team has introduced and participated in several social initiatives to the benefit of the company, including blogging, Twitter and Facebook activity, and a wiki for internal collaboration as well as external publication of technical documents.





5 Email interview with Jay Baer.