CIDM

March 2019


Thriving in an Environment of Change


CIDMIconNewsletter Neeraj Bhatia, Guidewire Software

The enterprise software landscape has gone through several changes over the last few years. While some changes have been incremental, others have been significant enough to force a rethink on how we manage documentation. This is our story of transformation, of how we adapted and responded to changes coming our way from multiple directions, and what we learnt through the process.

Changing Enterprise Software Landscape

Traditionally, enterprise software companies would build large monolithic products and release them every 12 or 18 months. These products were then installed on servers at customer premises and the deployment typically involved a long configuration process.

For these products, documentation teams would build large documentation sets and release them every 12 or 18 months, along with the products. There were maintenance releases in between, but the typical pattern was “large, monolithic products supported by large, monolithic documentation sets.”

But this model was changing. After years of talk about utility computing and managed services, the transition to cloud was more than just a buzzword. Several companies had built cloud-native platforms and software, and practically every enterprise software company was talking about adopting a cloud-first strategy. We were not immune to this change. (See Figure 1).

At a basic level, this change meant that software would no longer be installed at customer premises. And that software companies would be responsible for administering and managing the software. This would require rearchitecting monolithic codebases into smaller, independent modules called services (or microservices), which are made available to customers via the cloud.

This was a fundamental shift in the way we built and released software, and that required us to change the way we thought about documentation.

Changing Documentation Needs

The shift from large monolithic products to modular services meant that our large documentation sets also needed to be broken into modular chunks of reusable information. Also, the software was not going to be deployed on customer premises, so we needed to be able to host the documentation.

In the traditional model, we built one-size-fits-all products, and every customer got the same product and feature set. Now, customers could build solutions based on their needs by subscribing to specific services. So, we needed to be able to assemble our content chunks to build targeted solutions. (See Figure 2).

The move from long release cycles to frequent software updates, sometimes on a weekly basis, pointed to the need for a modern and efficient build and delivery system.

But that was not all. There were other changes happening around us, which were affecting our approach to documentation.

We were growing at a rapid pace. Our product portfolio grew exponentially, with several new products, new solutions, and dozens of add-ons and extensions. We made multiple acquisitions and went into several new geographies, all of which meant more content and more languages to translate our content into.

We also needed to respond to changing customer expectations. Most usability studies and customer surveys pointed to the fact that users do not have the time or patience to browse through information in manuals. They want to search for answers to their questions, they want the answers now, and they want the answers in the context that they are in.

To effectively respond to these changes, we had to change the authoring and publishing infrastructure, our toolset, processes, and deliverables—almost everything associated with the content development lifecycle was set to change.

Decision Time

There were several decisions to be made, some of which I have listed here.

  • Should we manage the change ourselves, or should we hire a consultant?
    While the change seemed overwhelming, we decided on managing the change ourselves because we felt we had the required expertise and experience within the team to set the direction, to make the required decisions, and to drive the project.
  • To DITA or not to DITA?
    This was a no-brainer. After looking at options vis-à-vis our needs, we decided soon that we would adopt the DITA standard.
  • What about tools?
    We had to change our entire tool chain. We had to pick new tools for authoring, for content management, and for delivery.

To make these decisions, we formed work groups that would focus on each of these areas. Each work group was assigned the responsibility of doing research, coming up with requirements, comparing available tools, and eventually creating a short list of tools for detailed investigations.

Getting Stakeholder Buy-in

For some changes, you can have a top-down approach. But a change this wide requires buy-in from various stakeholders. I will mention two stakeholder groups: writers and executives.

Getting Buy-in From Writers
The documentation team was very supportive of this change. There was complete agreement on the new direction. However, there were differences of opinion on how to get there.

Some team members were enthused about opportunities to learn new skills and the possibility of new career avenues. Some had apprehensions about the large scale of changes, and potential job insecurity.

Here are some things that we learnt through this process of getting buy-in from team members.

Separate Out the Long-term Vision from Near-term Goals and Execution Plans
A large multi-year project involving several changes might seem intimidating for some team members. Break down the changes into smaller chunks that can be executed in phases.

Hear Everyone’s Point of View
It is important for team members to feel that their point of view was heard and acknowledged, even if it sometimes seems like an ineffective use of meeting time. You do need to set boundaries so that conversations stay on course.

Watch Your Naysayers
You might do everything right, but you still might have team members who refuse to accept change. Sometimes team consensus starts shifting towards the loudest voice in a meeting. It is important to recognize this behavior and address it in a timely manner. Do not let naysayers drive the discourse or affect team morale.

Acknowledge Mistakes
A little humility goes a long way. The team appreciates it when you are open about acknowledging mistakes, whether about decisions that you made, or about process issues.

Getting Buy-in From Executives
Executives have little time or patience, and they have their own language and worldview.

Speak Their Language
Executives understand costs, timelines, and returns on investment (ROIs), and you must include these along with your rationale when you present your case.

At the same time, it might be helpful to familiarize them with some of your terminology. The executives in my organization may not understand structure or reuse, but they recognize the term DITA as a good thing.

Messaging Matters
We positioned our project as one involving infrastructure and process updates to improve the product experience—not just the documentation experience. And that what we were trying to do was analogous to the overall shift in technology—moving from monolithic blocks to modular chunks of reusable information. That message seemed to resonate well with the audience.

Consider Their Risk Appetite
Every organization has a different level of risk tolerance. Factor that in when you make your proposal. To reduce the risk perception associated with your project, do your homework well, and have solid data to back up your proposal.


Everyone wants to look good. Share the goodness and you will increase the chances of project approval and success. It’s part of the corporate success mantra.

Set the Right Expectations
Even as you try to sell your project to executives, make sure that they have a good understanding of risks and costs. It is important for them to understand that changes of this scale require several years to complete. And that there might be trade-offs to be made between on-going release work and work towards such future-oriented infrastructural changes. (See Figure 3).

Vendor Selection

We followed a fairly standard process to select our CMS vendor. We started with market research, built our requirements list, sent out requests for proposals (RFPs), and had multiple rounds of conversations with vendors. As we iterated through these discussions, we narrowed down our choices. Towards the end of the process, we shortlisted two systems, which we tested extensively before making our final selection.

We learnt that while having a list of requirements is a great start, flexibility is key. This is because as you learn and discover new things, requirements tend to evolve.

We also learnt that there are other factors influencing vendor selection.

  • Do you pick the market leader, the one with most features, or the least expensive one?
    There is no right answer, but these are things you would consider as you factor in your budget and other constraints.
  • Which requirements are most important to you?
    It helps to separate out your must-haves from the nice-to-haves, so you can pick the vendor who meets most of your must-have requirements.
  • What do RFP responses really mean?
    When it comes to reviewing RFP responses, it is important to understand the difference between what is supported out-of-the-box and what requires additional configuration.
    When the product is installed, an out-of-the-box feature is immediately available for you to use. However, a feature that requires configuration might imply a simple change, or additional Services engagement, which has a financial implication.
  • Are they a good cultural fit?
    A content management system is not a piece of software that you buy off-the-shelf and then forget about. This is an ongoing engagement. You will end up working with the vendor on upgrades and additional features, and you might consult them on issues related to architecture, automation, DITA usage, and publishing. Vendors often have a good pulse on the industry as they work with multiple clients, and often bring a fresh perspective.

Execution
Here are some highlights of the things that we learnt during the execution phase of the project. (See Figure 4).

Paperwork Takes Time
All organizations have bureaucracy. From building your statement of work and finalizing contracts to getting clearances from multiple departments, paperwork takes time. So, plan time for this time, and then add adequate buffer for each stage. It took us over three months to get the required approvals.

Have a Training Plan
Make sure that early adopters have access to training when they need it, and that they document snags and workarounds for teams that come on board later. Note that if you schedule training very early in the project, team members might not remember what they learnt when they start working in the new system.

Accept and Adapt to Change
Your initial assumptions will get tested as you gain more hands-on experience and learn new things. Our initial DITA content model was based on several assumptions and a mapping of styles and formats to DITA tags. Later, as we started porting content to the new system, we ended up expanding our content model, and in some cases, reversing earlier decisions.

Do Not Try to Boil the Ocean
Convert your content in phases. We decided on converting a small documentation set first. For our larger products, we targeted maintenance releases first, so we could identify issues and fix them in time for major releases.

Regular Communication and Status Visibility Help Increase Accountability
We built a dashboard to track overall project status. From the dashboard, one could drill down to detailed status pages for each project phase. Maintaining project status at a central, visible location made the process very transparent and kept team members informed and motivated through the process.

We also had regular sync-up meetings with our CMS vendor, which made sure we were on the same page and helped us resolve several issues through discussion.

Having the Right Team Matters
If you do not have the right technical skills and subject-matter expertise in the team, consider working with a consultant. For successful change initiative, you need a mix of champions and early adopters, people who question status quo, and people who can execute.

Do Not Underestimate the Time or Effort for Content Conversion
You could convert your content in-house or you could outsource the conversion task. Either way, do not underestimate the effort, whether for pre-conversion, conversion, or post-conversion. Each step is important and takes time. We converted our content to DITA in phases over a two-year period.

What is Next?

Now that we have the right tooling, infrastructure, architecture, and processes in place, we are in a position to support the evolving content needs of our cloud products, including embedded assistance, walk-throughs, videos, or content for chatbots.

We have significantly improved the efficiency of our build and publishing process. And we are close to launching a microsite for documentation, which will give us streamlined delivery, user feedback, analytics, and better search, and will improve the content experience for our users.

Beyond that, I do not know what other changes we can expect. However, having gone through this transition, we are ready to tackle the next level of changes. This experience has helped us evolve as a team that can not only adapt and respond to change but can also drive change.CIDMIconNewsletter