Documentation Anti-patterns: Open Stack


I saw references to a project called “OpenStack” on technology web sites and was curious about it. So, I went to the OpenStack web site hoping quickly learn more about it. What I found instead was a puzzling collection of marketing speak, jargon, and technical details. The OpenStack project web site, like that of so many others, won’t simply tell you what it is.

What I wanted was a basic, jargon-free description of the project and a list of business problems it is intended to solve. What I got was this,

OpenStack is a global collaboration of developers and cloud computing technologists producing the ubiquitous open source cloud computing platform for public and private clouds. The project aims to deliver solutions for all types of clouds by being simple to implement, massively scalable, and feature rich. The technology consists of a series of interrelated projects delivering various components for a cloud infrastructure solution.

This jargon-filled, marketing pitch tells me nothing at all. After wading though pages of documentation it looks to me like OpenStack is a set of APIs for building cloud-based applications. But I’m not sure that is correct and I don’t feel like investing more time in it.

This anti-pattern is the Basic Description Failure. To avoid it, project and products owners should:

  • Describe what your project is using plain language and with a minimum of jargon.
  • Make this description easy to find. Be respectful of people’s time and don’t make them wade through pages of documentation for basic information.
  • Explain what business problems your project solves. Why should anyone use it or care about it? Assume they don’t care and that you have to win them over.
  • Explain the benefits of your project in context. For example, why your project is better than other existing or related solutions.
  • When giving an overview of your project avoid: technical details, long detailed feature lists, vision statements, and the project’s history. Technical details and feature lists will be of interest once you have convinced someone to care about your project.

People want things to be easy and to be relevant to their needs. Tell them how your project is going to solve their problems and you will get their attention.



Categories: Documentation

Tags: ,

Share Your Ideas

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: