Join The [Technical] Conversation: An Argument For Open Software Documentation

Amanda Cross

by Amanda Cross, Documentation Manager, ExactTarget

[Editor’s Note: Don’t miss “How Interactive Documentation Builds Corporate Value (and Esteem from your Colleagues)” Friday, August 12 at 10am PDT/1pm EDT — a free, one-hour discussion between Scott Abel, The Content Wrangler, and Amanda Cross, Documentation Manager, 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 your 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 identifying or private information about customers, employees, suppliers, etc.
  • 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 instead, make a single, 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 I see for making documentation open, 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:

  1. What it is
  2. Why you would want to use it
  3. How to make it do what you want/need 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

Documentation isn't supposed to be a secret. It's loaded with things you want people to know.

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.

Fear of being hacked is also a reason some organizations shy away from open software documentation.

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 it1’?” 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.

Note: 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.

Documentation is a proactive customer care channel, says Tristan Bishop

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.”

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.

a mistakenly sent tweet by a Red Cross employee turned into good publicity for a brewery and increased donations for the Red Cross

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”.

Consider a recent red-face moment by an employee at the Red Cross, who accidentally sent a message about getting drunk (intended as a private message to a friend) via the Twitter account of the Red Cross. The Red Cross responded with humor and the mistake ended up resulting in increased 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.”

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.”

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.

Making documentation findable -- exposing it to potential customers -- is driving site traffic, and, as a result, qualified leads to his sales team, says Aaron Fulkerson

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 article “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.”

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.”

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.

You can try and silence those who share negative views or you can join the conversation

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 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 caveats.”

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.

About Amanda Cross

Amanda Cross is the documentation manager at ExactTarget, which was #243 on the Deloitte Technology Fast 500 Ranking, 2010 and #1,404 on the Inc. 5000 Fastest Growing Private Companies in 2010. Amanda has over 10 years of experience in technical communication and technical information management, specifically focusing on bringing structured content methodologies to high technology companies.

Amanda combines a nearly obsessive passion for information with another nearly obsessive passion for using automation to improve lives, making her, arguably, the single-most boring person in the world to get into a conversation with over the water cooler.

Amanda Cross Live! [Friday, August 12 at 10am PDT/1pm EDT]

Don’t miss “How Interactive Documentation Builds Corporate Value (and Esteem from your Colleagues)” — a lively web-based discussion between Scott Abel, The Content Wrangler, and Amanda Cross, Friday, August 12 at 10am PDT/1pm EDT. During this one-hour free webinar, the two content professionals will discuss common myths about the dangers of making documentation social. You’ll learn how joining the online conversation provides you with opportunities for market innovation, building your brand, improving customer experience, and driving revenue. The two will also talk about strategies you can employ to convince others in your organization that using social tools are essential for building customer engagement.

Register today!

Additional resources

Want to learn more about social documentation? Read “The Future of Technical Communication Is Socially Enabled: Understanding the Help 2.0 Revolution” by Scott Abel, The Content Wrangler, in the April 2011 issue of Intercom from the Society for Technical Communication.

Tags: , , , , , , ,

3 Responses to “Join The [Technical] Conversation: An Argument For Open Software Documentation”

  1. Ellis Pratt August 6, 2011 at 7:35 am #

    Thanks Amanda

    In July 11, we carried out a survey of Technical Writers in which we included a few questions about user generated content. We followed this survey up by interviewing some Documentation Managers based in the UK (the details of our findings can found on the Cherryleaf Technical Authors Blog

    We found the main reasons why user documentation was not published on Web sites (i.e. searchable on Google) were:

    The application was bespoke and/or specific to a single customer.
    The Support Department felt it would lead to fewer customers signing up for a Support contract.
    Competitors might read the content.

    We also heard that senior management often had a traditional view of what a user guide should look like.

    So it might be wrong to pin all the blame on Technical Writers when looking for the reasons why more organisations haven’t embraced user generated content.

  2. Ellis Pratt August 6, 2011 at 7:41 am #

    Amanda – could you delete my comment (and this one too) – I’ve just realised my comment doesn’t really relate to your post. Apologies, too early in the morning, too many distractions etc

  3. Amanda Cross August 10, 2011 at 2:32 pm #

    Hi, Ellis,
    No worries at all. I agree that technical writers shouldn’t get the blame for the closed-mouth approach many businesses take. In fact, “blame” isn’t even the right word because there’s nothing really wrong with playing your cards close to the vest. It’s just that you can do so much _better_ with openness.

    Secrecy in business isn’t specific to technical communication, and the trend in customers demanding freer access isn’t either. But this is the opportunity we have to start making our businesses aware of the shift in the trend at the beginning instead of trying to catch up after our competitors have already gotten on board.


Subscribe To Our Newsletter

Join our mailing list to receive the latest news and updates from our team.

You have Successfully Subscribed!