Wet Paint: Behind the Jazz.net Deployment wiki

The Deployment wiki

As previously alluded, we’re trying to change the model for how we communicate CLM and Rational product information specific to deployment. Presumably we could discuss what we mean by deployment, but the jazz.net Deployment wiki says it best:

“… a single repository for Rational deployment guidance and best practices for customers, partners, and Rational staff beyond the basic product and support documentation. The scope of the wiki is the full range of Rational products and solutions, but it focuses on advice for those that are most commonly deployed. The wiki assembles deployment information from many locations into a single community-developed and community-managed knowledge base.”

But really, what’s it for?

Having spent some time behind the curtain helping to get the wiki in order, I can speak to some of the behaviors we’re trying to improve:

  1. Bring accurate, relevant information to customers and practitioners
  2. Create a community where qualified experts can share their knowledge

We’re trying to consolidate the many different ways customers can find Rational product information, improve the shelf life of that information, and find a way to incorporate practitioner experience.

What’s wrong with the old model? (Well, nothing really…)

Back when, you’d open the box with the product diskettes and get a thick tome or two explaining how to install and use the software. Printed documentation seems to have gone the way of cassettes and eight-track tapes. Online documentation seems to be the current trend. Yes, trees are saved and cycle time reduced. I’m not completely sure that wikis represent the state of the art for documentation and knowledge management but this isn’t the place for that discussion.

Going about this the right way

No surprise that those of us working on the wiki are some of the most articulate of the bunch. However, we are a very self-conscious crowd even if we’re trying to impose our view of the world. We’re constantly asking each other to review what we write and collate. We want to get the facts right. We want to help our customers.

As we keep our goals in mind, there are a few things we worry about:

  1. Too much frequent, spurious change
  2. Readers misunderstanding or misusing what we say
  3. Making statements which are just plain wrong

Readers arrive at wikis well-aware that the content may be in flux. Still, we want to minimize trivial changes. At the deployment wiki there’s a wrapper of legal statements and terms of use which protect all of us. Much of what we publish is driven by common sense. We’re also constantly keeping an eye on what each of us do, not to police, but to be sure we’re doing our best work everywhere we can.

Humble beginnings

My work on the wiki started with the Troubleshooting Performance section. We assembled an excellent International team straddling development and customer support. At the end of February 2013, the Performance Troubleshooting Team locked itself in a room for one week. That we’d effectively take a clean sheet of paper and embark on a conceptually difficult topic was perhaps over-reaching, but we got an immense amount of work done. Supplied with generous servings of coffee, donuts and bagels, the team defined wiki structure, authored dozens of pages and figured out several necessary behaviors useful for the wiki’s more straightforward pages.

You might have thought we’d start on more direct material. That is, begin with “How to make a peanut butter and jelly sandwich,” rather than jump right into “Let’s figure out why you’re having trouble making a sandwich.”

Very often, the best instructions are sequential:

  1. Desire a specific result
  2. Assemble ingredients
  3. Follow sequential steps
  4. Arrive at result

Inventing theory

Troubleshooting presumes something, anything, may have gone wrong, and requires a diagnostic vocabulary. We had to write pages on how to solve problems, before we even picked the problems we wanted to solve. We had to agree on how to frame issues so that readers could use our pages to comprehend their own concerns and use our pages for help.

  1. Desire a specific result
  2. Assemble ingredients
    1. How do you know if you don’t have all the ingredients?
    2. Might some of the ingredients be faulty?
  3. Follow sequential steps
    1. How do you know if you missed a step?
  4. Arrive at result
    1. How might you determine you haven’t achieved the result?

We settled upon situations as the name for the things we were trying to help solve and write about. We tried to come up with reasonably narrow situations, and applied some of our Agile techniques to frame situations:

“As a <user> trying to do <X action>, I encounter <Y performance problem>.”

We discovered that situations fell into two categories: situations which administrators were most likely to encounter (not necessarily product specific, more likely to be environmental) and situations which users were most likely to encounter (more likely to be product specific, not necessarily environmental).

Given performance problems often appear to end-users as a culmination of several problems, we decided that the situations we would discuss had to be discrete and specific: “How to troubleshooting performance of <feature>,” or “How to diagnose performance problems in <non-product component within an environment>.”

Because the pages are on an easily discoverable public wiki, the material had to be reasonably self-contained with clearly defined scope. We also had to add hints for where readers would go next should our pages not actually prove to be helpful.

We thought a lot about who our audience might be: The administrator situations and user situations seem obvious now, but they weren’t our original design.

Admittedly, maybe I worried more about theory than most. Or at least, the team let me worry about it while they were doing lots of research and writing.

Actual practice

Many of the situations required researching and writing background pages to explain key concepts even before troubleshooting started. A page on performance troubleshooting ETLs required explaining how to read ETL log files. A page on slow performance in web browsers required material about how to measure browser performance independently of CLM. A discussion of troubleshooting virtualized configurations required an introduction to virtualization concepts.

Each situation proposes an initial assessment to identify symptoms, impact/scope, timing/frequency and any other environmental changes. These are the basics of troubleshooting. Then there might suggestions about how to collect data, use tools, or complete an analysis. Finally there are the paragraphs readers expect where possible causes and solutions are itemized. Not every cause and solution applies to everyone. We didn’t want to create a greater burden for support by suggesting things that were wrong, irrelevant or confusing.

As mentioned above we also wanted to make sure readers could find their way to support, other IBM and generally available material. As much as we worried about a top-down structure (entry pages, secondary pages, etc.), we are well-aware that folks might arrive at a page from an Internet search.

For consistency, we created a template for writing our pages. At the end of our troubleshooting template are Ground Rules. They look simple, but they are easily internalized and effective.

Ready right now, and preparing for the future

We’re desperate for feedback. Each page has a comments section which we monitor. We’re considering updating the wiki platform with some “like” capability, as well as tie it closer to jazz.net’s forum.

We created a page where in-progress articles can be found, and suggestions for potential troubleshooting topics can be made.  So please visit the wiki and let us know what you think.