Helping the experts to document each client's solutions

Staples "easy button" edited for project codename "Big Easy," released publicly on IBM DeveloperWorks as the Toolkit for Custom and Reusable Solution Information

Summary

Problem

Enterprise clients care about and invest in solutions to address their business challenges. A solution usually consists of multiple products, often a fairly unique combination of IBM and other third party software. Yet we were struggling to provide clients with product technical information integrated and tailored to their specific combination of products.

A client-facing solution subject matter expert illustrated it in his team's report, "A Day in the Life of an IT Specialist: Proof of Concept Planning and Preparation."

A lot of the information we have, such as in Information Center repositories, is organized to be brand specific, yet we find our software stacks are quickly becoming cross brand...

Questions from clients can be challenging to answer. Is the information available? Can I find it? Too many places to look! Can you show me how these products work together? How do we install these products?... Do I have all of the software I need?

- IT Specialist

Context

As the information architect of a major product's technical documentation, I was aware of the IBM information community's strides in standardizing, integrating, and improving the ability to find information about each of 200+ products, individually. Some of us even were advocating and piloting how to improve integration across our products and brands.

Still, clients and our experts in their solutions were having difficulty:

Finding product information relevant to each of the client's products

Aggregating it into a coherent, tailored collection about this solution

Updating the information collaboratively over the solution lifespan

Catalyst

It was unclear and unexamined who could or should "own" improving on these pervasive and urgent client pain points.

Broadly speaking, I found that the architecture community felt responsible for multi-product technical solutions, but left the documentation to the design and content professionals in the information community.

Meanwhile, the information community felt responsible for documenting products thoroughly, but we usually lacked line of sight to specific client solutions. We struggled to document even the most popular combinations of past product versions at scale, when our business imperative had us focused on documenting the next product version.

I also noticed that to the extent we were taking action to solve the problem, the architecture community and information community were doing it on parallel but complementary paths. Both groups had initiatives to make software assets and product information (respectively) more modular, reusable, and capable of integration across products and brands.

Collaboration

I proposed, recruited, and co-led the first workgroup to address this client need across organizational boundaries, with architecture and information community colleagues collaborating in new ways. This involved persuading the architecture community that their help was essential to improving the information situation. From 2006-2009, 22 of us explored the problem, performed research, and defined a vision.

Solution

We reached a major conclusion that we needed to enable the solution subject matter experts to aggregate and organize solution-level information from mostly existing product-level information.

Only these experts knew "the last mile" from generic product information to specific solution information. Information design and delivery best practices could be taught and automated. We imagined easy solution information workflows, tools, and templates that integrated with their existing workflow and tools, such as using Rational Solution Architect (RSA) to model solutions.

1. We developed solution navigation templates embodying both best practices for information design and solution expertise from a broad array of client-facing roles with different perspectives on the solution lifecycle.

2. We piloted automated capture and aggregation of product information into solution information. We did a proof of concept to demonstrate the end result while gathering time and cost avoidance metrics.

3. With incubator funding, we designed and delivered on the IBM external site an easy graphical user interface as an immediate stopgap solution.

4. From a research study, we captured pain points and made 60 recommendations for the information community to make our product-level content more findable and reusable in client-facing solution information. We worked with the relevant parties to drive our recommendations into their strategic or funding plans.

Why this solution?

Design research and the process informed our choices, as did forming a passionate, diverse workgroup and then using our networks to interface with more than 50 teams/functions in IBM for their perspectives.

Organizationally, a key discussion and decision point was about the respective roles of the architecture and information communities and the personas therein. What should the ecosystem look like to function most effectively to deliver solution information? This is how we aligned strongly on uniting the architecture and information communities to enable the client-facing personas acting as solution experts to do it themselves.

It capitalized on what each community already was doing to the solve the problem. Any path based on trying to centralize and scale the production of solution information at the hands of either or both communities ran into the "last mile" problem - only the on-site solution expert knew enough about it, including how fancy to get for a specific client project. Also, it seemed more realistic to distribute a variable, nominal cost to each client project than to drastically expand either community's mission and funding.

Technologically, for the "Big Easy" graphical user interface, we went with open source standards already in use by the architecture and information communities. A key discussion and decision point was between building on the Eclipse help system or building a sleek new web application.

Building on the Eclipse help system:

Familiar and compatible with RSA tool used by many solution architects

Familiarity breeds contempt (sentiment of it being older technology)

Familiar to many in information community as current delivery method

Fully open source based for integration, automation, extension, fixes

Could develop something experimental now, quickly, "cheaply"

Developing a sleek new web application:

Not familiar in existing workflow of either community (standalone)

Wow factor, could position as a cool new tool to excite new adopters

Still could use standard formats for capturing and delivering information

Not open source - sacrifice extensibility and fixes by clients, third parties

Would take longer to find skills, develop, at higher expense

Design process

Here's a quick view of our steps and artifacts.

User research and validation (throughout)

Firsthand experience of some workgroup members

Interviewing solution subject matter experts (target persona)

Research study (deep dive)

Usability testing

Identify human needs and business objectives

Personas: We discussed and felt comfortable collapsing several organizational roles Into a "solution subject matter expert" archetype

Human problem (~empathy map) and pain points: Firsthand experience of some workgroup members; researching our colleagues who also were in solution expert roles; usability testing

Business problem: What was it costing us to keep delivering little to no solution information to clients? What might it cost to change? We found that delivering high quality solution information currently was strategic, but too cost prohibitive with existing methods (rarely done)

Vision and objectives: For example, to improve ease of doing business or to simplify solution ownership throughout the solution lifecycle. Looking back, we could have solidified the measurable goals using OKRs.

Envision usage scenarios by persona

Ecosystem: How might company personnel collaborate to address the client pain point? Who should do what in the process? What might be the technological enablers or architecture?

Roles (~personas): What are the typical skills, responsibilities, tools, and technology used by each persona in their workflow? For example, we personified the information community into two main roles: information producers (writers) versus those who organize, label, and package information for delivery (information architects and strategists)

Scenarios (~hills): For example, "in minutes, a consultant on a plane uses a locally replicated copy of a technical information repository to organize and package some of its content into the start of a solution-specific documentation for the next day’s client engagement meeting"

Gather and validate requirements for each scenario

Detailed requirements with me acting as a product owner

Align on an information architecture

Solution navigation template: Combining both communities' understanding to outline a soup-to-nuts set of information about the end-to-end solution lifecycle, including evaluation ("try and buy," demos, and proofs of concept) and end of life transition. This gives everyone who touches the solution throughout its lifecycle a guide for where to plug in the relevant information

Terminology: Glossary

Select the technology, constraining interaction and visual design

Described previously

Design the interactions

As-is and to-be journeys: Including an in-between journey

We also designed three interaction patterns or flows:

Steps for a solution expert to customize the solution navigation template and start plugging in content

Steps for an information expert to package their information as a modular “plug-in” to the solution navigation template

Steps for an asset repository owner or user to export hundreds of assets from a Lotus Notes database, RSS feed, or other aggregator, then quickly package it as a set of modular plug-in to various target points in the solution navigation template through automation

Outcomes and metrics

We looked at five main areas. Usage of the GUI was disappointing, but I have to be proud of the results, given this was a volunteer effort in addition to our day jobs. Many workgroup members stuck with it for all three years. We laid data-driven conclusions and recommendations at the feet of both communities. We made it feasible for solution experts.

Impact on feasibility. We made it feasible to deliver a maintainable, extensible coherent solution information viewer tailored to the client's actual product combination (see cost avoidance and time savings)

User experience improvement. It went from the client receiving some documents by email , box folder, etc., to receiving a coherent experience with an appropriate level of polish at the discretion of the solution expert. I created the following prototype to demonstrate the possibility and estimate the minimum potential cost and time savings.

Cost avoidance through automating information plug-ins

Before automation: 71 labor hours or about $5325 per solution

After automation: 6 labor hours or about $416 per solution

Time savings

Assumes a one-time cost to automate steps in 3 interaction patterns

Assumes execution in a tool familiar to solution architects (RSA)

Reduced to a few minutes, from starting range of 30 mins to 17 hours

Usage

Incubator led to 50+ GUI downloads from nine global geographies

Documentation translated into three languages

Two known client engagements

Pilot usage by internal groups testing and documenting solutions

Reflections from today's perspective

This effort pre-dated systematic adoption of Design Thinking in IBM, but many of the activities were similar, as previously noted (classic design methods). I also wish I would have known about Objectives and Key Results (OKRs) and RACI diagrams.

Some topics I would like to have explored more:

How low would the "cost of entry" need to be, to attract the many client-facing solution experts who are working on billable hours? Did we need to further segment our roles/personas?

Did self-selection of workgroup volunteers who were solution experts lead to skewed representation of the user needs? Did we need to do more research - and perhaps observational studies instead of mostly interviews?

We hypothesized the ideal roles of the architecture community, information community, and solution experts in delivering solution information, but did we need to do more to cultivate widespread buy-in for this culture change? To what extent was it an immovable object? ("Culture eats strategy for breakfast").

What are the possible organizational incentives? The levers?

How might we have applied IBM Design's recent Universal Experiences framework that outlines best practices for designing the client experience (buyer, user) throughout the product lifecycle, starting with discovery?

UNDER CONSTRUCTION. Read onward for the gory details and artifact images.

Forming a team

We needed the right team to explore the problem. I pitched a new workgroup to the architectural community, where the client-facing solution experts gathered. I knew I could recruit additional volunteers from my "native" information producer community, comprised of Total Information Experience (TIE) and Information Development (ID) practitioners.

Crossing usual boundaries

It was unprecedented to start an information-oriented workgroup in the architecture community, instead of in the information community. A workgroup crossing these boundaries ruffled feathers in both communities, but I convinced an architecture community leader of my vision.

I proposed, recruited, and led a 22-person IBM Software Group Architecture Board workgroup on scalable, repeatable approaches to documenting solutions

Uniting parallel efforts

I'd noticed parallel and potentially complementary efforts in the two communities, both about modularizing and integrating reusable assets.

The information community was making strides to modularize, reuse, and integrate various sources of product-level technical documentation. Its Integrated Information Plans (iiP) initiative encouraged coordination, for example, whether Support Engineers or Product Doc writers should document product Troubleshooting.

To this community, I proposed that integrating information into cross-product solutions was at least as important, even if the community - including me - hadn't seen a practical way for us to "own" solution documentation because we weren't experts in a client's unique solution.

Meanwhile, the architecture community was trying to gather, modularize, reuse, and integrate assets such as architectural pattens within and across products that comprise client solutions. To this community, I proposed that internal and client-facing documentation is just another type of asset.

Learning from one another

By collaborating across the architecture and information communities, we'd come to appreciate a valuable skills transfer between the groups. For example, this diagram shows the exchange between the Federated Integration Test (FIT) team tasked with testing common product integrations and the Information Development (ID) community.

Ultimately, the workgroup would touch more than 50 other councils, workgroups, and teams, company-wide due to the scope of the problem and solution recommendations. I learned about many client-facing and architectural teams and initiatives I'd never known until I lifted my head up from the information community.

Scoping our mission

After some basic level-setting, the workgroup drafted our charter, which was important for determining when the workgroup had run its course. One example is that we sought to deliver a proof-of-concept (POC) based on a strategic Service-Oriented Architecture (SOA) scenario in the small to medium business (SMB) space.

Defining the problem

Human problem

IBM clients, partners, and the IBM personnel who help them to implement and maintain their multi-product solutions were having a frustrating experience trying to find and organize the technical information corresponding to their unique solutions.

Clients seek information that matches their solution

The workgroup reached a major conclusion key to defining our target personas: We needed to empower the client-facing solution experts to document the solutions. Why?

Only they know the client's unique solution

The solution, by definition, doesn't yet exist when the information community is doing its job to document in a "generalized" way each product that comprise the solution

Solution expertise is the main skill needed - we can teach, make easy, and automate the information design skills

They take the client solution the "last mile." Even when supplied with product-level information for each product in the solution, they're familiar with the remaining gap in documentation, which they or the client might fill

Anecdotal evidence

The downside of having so much good product technical information available was the challenge of helping clients or client-facing personnel to sift through it to find information relevant to their unique solution. For example, more than 200 mostly product-specific information centers were available at the time.

Solution owners and experts must forage for relevant information

A client-facing solution subject matter expert provided these anecdotes in his team's report, "A Day in the Life of an IT Specialist: Proof of Concept Planning and Preparation."

A lot of the information we have, such as in Information Center repositories, is organized to be brand specific, yet we find our software stacks are quickly becoming cross brand.

- IT Specialist

Business problem

Current way is unaffordable, so it doesn't scale

Through their networks and from their own experience, workgroup members from the architecture community were able to characterize approaches to documenting solutions today. Often, they could afford to do no more than sending a cache of documents that they were able to gather, and were in the same position as clients in having to forage for relevant information in the vast array of product information in various locations throughout the company web site.

Comparing as-is and to-be approaches

But can we afford not to improve it?

Concluding that documenting our clients' unique solutions was strategic, but cost prohibitive, our workgroup decided to look for not only "flat out" or ideal solutions to the problem, but for what we could do right away at a low cost of entry to "outpace competitors."

Solution information is strategic, but cost prohibitive currently

Vision and requirements

We introduced our solution information framework requirements relative to the next best thing at the time. IBM Redbooks were a benchmark for solution documentation because they often involved a team of technical experts documenting how they integrated a multi-product solution. However, they could not be produced at scale, nor were they tailored to a client's unique solution.

High level requirements for a solution information framework

Exploring solutions

This section describes the design approach of the workgroup I co-led with a design research specialist. Note:This project predated the transformation of IBM Design and its new emphasis on Design Thinking methods.

What we delivered and why

Our workgroup began to imagine how we could support the user journey of the solution subject matter expert who wants to assemble solution information for a client - ideally, in a way that's integrated into their existing tools and workflow, such as modeling software.

A simple view of a to-be user journey

Graphical user interface requirements overview

User roles

We asked, What are the typical skills, responsibilities, tools, and technology used by each persona in their workflow? For example, we personified the information community into two main roles: information producers (writers) versus those who organize, label, and package information for delivery (information architects and strategists).

User roles, skills, and tasks

We discussed and decided we could safely collapse a variety of roles into the persona of a solution subject matter expert:

Business and IT consultants

Channel and ecosystem partners

Client engagement teams (implementers)

Demo and sales teams

Solution architects on product teams involved in popular solutions

Solution testing teams creating implementation roadmaps for clients

Support and SWAT teams

Personnel employed by the client

User research into pain points

We did an in-depth research study with a team of solution subject matter experts, documenting their challenges and pain points in documenting solutions (in their case, fairly common product combinations, as opposed to unique client solutions). See the deliverable deep dive for details.

To-be ecosystem

An advanced, longer term ecosystem vision

Information architecture

We relied on both communities' understanding to outline a soup-to-nuts set of information about the end-to-end solution lifecycle, including evaluation ("try and buy," demos, and proofs of concept) and end of life transition. This gives everyone who touches the solution throughout its lifecycle a guide for where to plug in the relevant information.

Solution navigation design - sorry for the grainy image

To-be scenarios

This are akin to our hills. For example, "in minutes, a consultant on a plane uses a locally replicated copy of a technical information repository to organize and package some of its content into the start of a solution-specific documentation for the next day’s client engagement meeting."

Scenarios

Journeys

We outlined as-is and to-be journeys.

An advanced to-be journey

As-is: Client receiving some documents by email , box folder, etc.

To-be: Client receiving a coherent experience with an discretionary level of polish

Interaction design

We designed for three interaction patterns or flows.

Three main scenarios to support

Steps for a solution expert to customize the solution navigation template and start plugging in content

Steps for an information expert to package their information as a modular “plug-in” to the solution navigation template

Paragraph.

Testing and pilots

The toolkit underwent usability testing with IT Architects and IT Specialists, in addition to a pilot program with a team of solution experts tasked with identifying repeatable and reliable ways to construct, sell, and deploy cross-brand software solutions, which they would document as "adoption routes" or roadmaps.

Usability test plan excerpt

Technology

Vision for technical framework, long term

For the "Big Easy" graphical user interface, we went with open source standards already in use by the architecture and information communities for reasons outlined in the summary. A key discussion and decision point was between building on the Eclipse help system or building a sleek new web application.

Concept diagram of how information plug-ins work in the Eclipse help system

Developed Design Pattern Toolkit project enabling non-professionals to generate Eclipse documentation plug-ins from an XML spec. Could piggyback on existing functionality (JET) being used in Rational Software Architect (RSA) tool that they already use.

Researched and developed an information architecture, implemented in XML. Two templates: 1. Packaging technical information to reuse in a solution context 2. Comprehensive solution table of contents to populate with the packaged content.

How our automated patterns and GUI consume and product the same plug-ins

Implemented solution navigation and content modules as Eclipse plug-ins because this already was familiar to many in the information community for delivering information.

Solution experts can use our GUI, our automated patterns in their RSA tool, or both

Measuring outcomes

Human outcome

It went from the client receiving some documents by email , box folder, etc., to receiving a coherent experience with an appropriate level of polish at the discretion of the solution expert. I created the following prototype to demonstrate the possibility and estimate the minimum potential cost and time savings.

Prototype incorporating hundreds of documents from multiple information sources

Business outcome

Feasibility of documenting solutions

Before and after calculation

Cost avoidance details

The existing method for "solution information" is to send a collection of documents via email, a box folder, or so on. The other "as-is" way would have involved something like the following workflow, using existing professional information development tools and techniques. The following diagrams compare the savings from automating many of those steps using the patterns technology in the Rational Software Architect (RSA) software used by many solution architects at the time.

As-is

Paragraph.

To-be

Time savings

Recall the three patterns largely automated in RSA.

Three patterns

Time savings calculations

Downloads and usage

Within a few months of availability, the toolkit was downloaded more than 50 times in 9 geographies. I did find the tool included on at least one site that copies tools and redistributes them. It was used for two client engagements, of which I'm aware.

In addition to a series of articles I wrote for IBM developerWorks, "advertising" of the toolkit included three Software Group Architecture Board "All Hands" presentations for audiences of around 800 people, and three internal conference presentations.

Deliverable deep-dive:

Graphical user interface ("Big Easy")

With the content templates in place for a solution navigation and tree and information modules that plug into it using Eclipse plug-in technology, the workgroup then pitched an easy graphical user interface (GUI) in there form of an Eclipse-based toolkit to help solution experts document their clients’ solutions. We gained incubator funding to work with a development team in Beijing, with me leading the project in a product manager role.

Drag and drop content into the navigation tree

Include office documents (variety of formats)

Import content as standard Eclipse plug-ins

Include documents in batches

Mix online and local documents

Search for content from within the tool

Package the solution information for your client

Documentation

Deliverable deep-dive:

Research study and recommendations

With a seasoned design research specialist, I co-led the workgroup to draft requirements for promoting scalable, repeatable approaches to solution information. This led to about 60 recommendations for content, processes, and infrastructure that we handed off to 15 catchers representing 4400 technical information practitioners in the company. We negotiated with the appropriate owners to drive the recommendations into Fall/Spring budget planning and into practice.

Recommendations were a key deliverable

Research study question

Glossary

With a project of this scope, simply sharing the same understanding of terminology can go a long way. We took the time to document our terminology in a glossary.

Glossary