Revamping a product tome

Summary
After many years of updating our very large Tivoli Storage Manager (now IBM Storage Protect) Administrator’s Guide by cramming in details about new features, we came to the conclusion that a new documentation strategy was needed. The result was a set of best-practice solution guides for the product.

Problem & user needs
At 1,200+ pages, the Administrator’s Guide was a bloated encyclopedia of product concepts and procedures that provided little in the way of actually implementing a comprehensive solution to meet business needs. Users needed more prescriptive guidance on how to install, configure, and then monitor a focused implementation.

Role
Project team lead, information developer, & graphic designer working with the Tivoli Storage Manager server team writers, developers, project managers, and architects

Key contributions

  • Co-led a workshop with development and (a budding) design team to figure out a strategy for the rework.

  • Lead a team of 4 writers to rework existing content & develop new topics.

  • Worked with our Beta coordinator to gather early feedback from existing users.

  • Coordinated with development and architecture teams on reviews and procedure testing.

  • Created several new architecture graphics to help show the workings of each solution.

Outcome & impact
The team developed a set of four solution guides that documented how to set up the product from start to finish. We created a comparison table to help users understand how the solutions were different and easily select one based on business requirements. Customers loved the “how-to” details and consumable format of the documentation that now helped them configure the implementation.

The story

When I joined the Tivoli Storage Manager team as a tech writer, our Administrator’s Guide was close to 1400 pages and those were in the days when manuals were still being printed. The volume and number of topics grew every year and without time to revisit old information, the guide ballooned to an overgrown dump of information.

One of our test architects, Jason Basler, wanted to help users get set up and running with the product quickly. He came up with an idea to help customers by providing them with a very succinct and focused set of deployment instructions which came to be known as our blueprints. They focused on a single type of implementation using disk-only storage, and could be adapted for small, medium, or large environments. This was quite a successful endeavor and got the wheels turning around an overhaul for our administrator’s guide. Using this blueprint model, we wanted to transform our documentation to be more than just a encyclopedia.

Overview for the blueprints, available from IBM support:

In early 2014, I worked with my manager and our dev team to partner with Jason on developing a plan to rework the Admin Guides. We held a summit in Tucson with managers, developers, testers, and writers to brainstorm on possible avenues. While the blueprints were great for one setup, we wanted to offer customers more options, from simple to more complex. Using the field knowledge from our summit participants, we settled on 4 most-likely scenarios that would cover the majority of our users. We also identified the most important points to hit with customers, which was more prescriptive guidance and roadmaps to implement these solutions themselves, without the need for a sales rep to guide them through every step.

Outcomes from the Administrator’s Guide rework summit:

As we began vetting these solutions with customers through our Beta program and the beginnings of a sponsor user group, we verified that we were focused on the right set of implementations. I led the team in determining how to restructure the guide based on what we needed to cover for a start-to-finish setup. We wanted to keep critical information intact wherever possible while developing new information to fill in the gaps. We had added complications of having to wade through 1000s of files and keep existing documentation updated for in-progress releases.

Our main aim was to be much more prescriptive and task oriented so users could follow the instructions in one of the guides end-to-end and it would all be relevant for their implementation. We wanted to curate useful, streamlined information that would actually help users accomplish the complicated task of setting up a server environment. So much of the current guide meandered and mixed lots of conceptual information in with tasks and reference without a bigger picture focus. We came up with a simple 5-step structure that all the guides would follow: Browse, Select, Provision, Implement, Monitor.

Our simple and focused recipe for the documentation steps:

We spent many months developing outlines, reusing content wherever we could, testing the procedures, and reviewing updates with our customers. I created new diagrams for all of the solutions and tried and add additional images and graphics throughout the topics for key concepts and reference information. Once details about all four of the solutions were available, we created a comparison guide to serve as our first recipe step - selecting the right solution. The first two solutions were published in fall 2015, just as I left my information development role and joined the design org as a new UX designer.

Updated documentation — An introduction to the multisite disk solution and a roadmap focused on a specific set of implementation tasks: