Vaijayanti Nerkar and Priya Shetye, BMC Software 
July 1, 2021

A few years back when BMC Software decided to tap the SaaS markets, the company started to invest in developing cloud-based products. For more than 20 years the BMC Software products were quintessentially on-premises products thus, our documentation strategy was centered around delivering information for an on-premises model. When we entered the cloud-based markets, we quickly realized that we would need a new strategy for the SaaS products. The move to SaaS brought about a lot of changes around installations, upgrade policies, patch policies, and so on.  Thus, it became important to formulate a documentation strategy specific to SaaS products. We could tell that it was going to be very different from what we were using for 20 odd years.

What are the differences between SaaS and on-premises policies?

The release cycle is one of the key differentiators between SaaS and the on-premise world. The release cycles in the SaaS world are much shorter. We deliver a major release every quarter. As a result, the releases are fast-paced and agile. The release backlog is more customer-driven than before. The cloud products are not “shipped” through an “Electronic Product Download” method. The product support strategy has also changed. Due to these key changes in the overall release process, we needed to respond by adapting to the new way of functioning. We had to optimize the documentation processes at many levels.

What changed in the processes?

The move from on-premises to SaaS brought about important changes in the processes as well as mindset. Let us first look at what changed in the documentation processes.

Documentation versioning — With the arrival of SaaS policies, the majority of the customers are now automatically upgraded to the current release. Very few customers have an exception and are just one version behind the current generally available release. The SaaS support policy now states that we only support the current and the previous release. Due to this we no longer need to maintain older versions of our documentation spaces. The cloud-based products have only two live documentation versions the “current” and the “previous”.

Terminology changes — The SaaS release brought in some new terminology, which was needed to be absorbed not just in the documentation, but across other functions such as Education, Support, DevOps and so on. Since the upgrades and patches are pushed to the customers, the service packs become push releases, version upgrades become version updates and so on. The initial effort to bring all stakeholders and functions to use the same terminology was huge. Eventually, the new terms were picked up and have become more stable in the past couple of years.

Stakeholder interaction — Few new stakeholders got added to our interactions. DevOps and Technical Marketing were such stakeholders. The DevOps and technical publications teams needed to be aligned closely during various milestones in a release. For example, about a month in advance of a major release the DevOps team needed to notify customers of the upcoming release and communicate, at a high level, the features that would be delivered with it. For this, the documentation team needed to create a Preview topic, which the DevOps team published for customers along with their release calendar. The Technical Marketing and Product Management organization became a key stakeholder as we needed to get the value realization uses cases and elaborate them in the related product documentation.

The interaction with the Support team becomes very crucial. They are treated as our first customer and they provide some vital inputs to the documentation. We have put in place a “documentation validation” process where the Support team tests the documentation by performing the tasks involved in a use case delivered in that release. They are not provided direct links to documentation or other self-help material. At any point while performing a task if they need help, they search for the information like a customer would and confirm that the information is findable and complete. This helps us tighten the documentation for any inaccuracies.

What changed in the content?

Not just changes in processes, a lot of changes were made in the content as well. Right from the content model to the type of deliverables, we revamped a lot of things.

Content model changes — For the SaaS products the customers do not perform installation and upgrades tasks. It is taken care of by the service provider (which is BMC in our case). Hence the installation and upgrade sections were deprecated from the content model. We added sections around onboarding and release preview. As we started to provide a lot of in-application help, our text-based documentation started to become leaner. The Getting Started topic became one of the most crucial topics as a direct link for this topic was added in the subscription email that went out to the new customers. We refurbished our documentation Home Page to give quick entry points to the major use cases catered by that product and to other learning resources like Communities, video playlist, knowledge articles and so on.

Rich media focus — Our SaaS products are new-age products and have an intuitive UI. As a result, we started to move towards “show” more than “tell”. We implemented an In-Application help, added more rich media content like videos, workflow or process diagrams, and tutorials. Our vision is to deliver 50% content through rich media, and not default to text-based documentation for information delivery.

Tone of voice and related changes — Due to more focus on the rich media and self-help we brought about a change in our tone of voice; it became more conversational than formal. The way we labeled our sections and headings changed. Our topics become more goal-oriented than feature-based. For example, earlier it was very common to see titles such as Managing approvals or Working with approvals. Now we are more thoughtful about the titles and try to give users an idea of the goal in the title itself such as Automating Self Approvals, Configuring Self Approval for tasks, and so on.


The move to the SaaS strategy came with a fair bit of challenges. The biggest challenge was around changing the writer’s mindset. We wanted the writers to avoid defaulting to text-based documentation. Thus, the User Experience plan or the documentation plan became an important artifact. This plan helps the writers to identify the right deliverable for the given use case. The writers analyze the information needs in terms of the persona the use case caters to, then determine how the information should be delivered, whether in a video, self-help flow, or text-based documentation. After a thorough analysis, they narrow down to the right mode of information delivery.

We also needed to invest a lot of time in training our writing team on the SaaS products on how they work as a standalone product, on what are their integration points, or how they work as a solution. We also trained the team on new tools that were used for delivering self-help.

While coping with shorter release cycles we did not want to compromise on the quality of the deliverables. So, we came up with some creative ways to optimize the quality processes like documentation validation and creating user experience plans. For example, we started the validation process for some use cases that are completed earlier in the release cycle, while keeping the cross-product use cases towards the end of the release. This helped us reduce the workload towards the end of the release without compromising on quality.

The journey continues

As we implemented new processes, we started to rely a lot on tracking the customer feedback. We needed to ensure that the processes and quality checks were working for everyone.

We have received a lot of positive feedback on some of our deliverables, like tutorials, diagrams, and videos. We regularly keep track of the customer comments received on the text-based documentation. For topics that are marked as “not useful,” we ensure to investigate what is it that is not working and improvise the topics to make them more user-centric.

Customer Delight is our mantra and we have a lot of checks and balances in place to ensure we are on the right path.

As a team we have learned to deliver release documentation every quarter, our next steps are to look at ways to support the bi-weekly product releases and refine our processes such that we meet the quality and customer satisfaction and continue with our SaaS journey.