This guest blog post was written by Neil Matheson, a Technical Writer at Avaloq. Neil joined Avaloq six years ago and was heavily involved in the project to migrate its documentation to MadCap Flare.
Founded in 1985, Swiss-based Avaloq is a global leader in digital banking solutions, core banking software and wealth management technology. It provides powerful cloud computing solutions for banks and wealth managers through business process as a service (BPaaS) and software as a service (SaaS). More than 150 banks and wealth managers with around CHF 4.5 trillion in assets managed worldwide trust Avaloq for its award-winning products and services. Avaloq is a subsidiary of NEC Corporation, a global leader in the integration of IT and network technologies. The company is headquartered in Zurich and employs more than 2,000 people around the world.
Avaloq provides extensive product documentation for its clients. About five years ago, we decided to switch from creating this in our previous tool, a DITA-based CMS, to MadCap Flare. So this seems like a good moment to think about what we’ve gained from the switch.
Our technical writing group used the DITA-based CMS, together with an XML editor, to prepare PDF documentation. The documentation was heavily structured, with specialized XML schemas for each topic and documentation type. The software solution itself had been customized to meet our specific needs. We uploaded the PDFs weekly to a custom database, and clients could search for the documentation they wanted via a form on a website, by ID, title, area or keyword.
We use Flare to produce HTML 5 and PDF documentation for our clients using single-source publishing. This is accessed through our product documentation site.
By switching to Flare, we’ve gained flexibility, speed, simplicity, and saved on cost. Some of the key advantages of Flare are highlighted below.
Flexible and Open
The first and most obvious change is that our primary delivery channel is now our HTML 5, though we still make PDF documentation available for most products. While the DITA CMS would have allowed us to produce a form of webhelp, this would have been based on a proprietary solution, not on an open standard as with Flare. Flare’s approach has allowed us to combine the documentation we produce with output from other sources to make the site more useful for users.
This flexibility and openness is important to us in a number of ways:
- Like many companies, Avaloq has changed its development approach, embracing agile methodologies. As this journey has progressed, it has meant changes to our workflow, which would have been difficult to accommodate with our old tool. Flare’s flexibility has allowed us to react dynamically and accommodate different ways of working to produce cohesive output for our users.
- Avaloq has developed and delivered new products and services, while continuing to support and develop its traditional offering. This means we now deliver more types of documentation. With Flare, this has been a simple process – we have created new projects that leverage existing resources or integrated new topics, TOCs and other resources into our existing projects. With the DITA CMS, the highly structured nature of the documentation and strict validation against its schemas would have made this a lengthy, technical, and expensive process.
- It’s not just the development methodology that has changed in the time we’ve been working with Flare –there have been changes in the corporate organization itself, particularly when Avaloq became a subsidiary of NEC Corporation in late 2020. Flare allowed us to respond immediately and quickly change our documentation to reflect the updated branding–a process that would have been far more complicated and time-consuming with the previous tool.
- New product categories and ways of working have been reflected in an increase in the number of formats in which we receive information. Flare allows us to simply import Microsoft Word files, markdown, HTML files and more. This allows us to quickly and efficiently include information from across the company in our documentation. We had one regular import into our old CMS, which used a specially written script and required a specific XML format. We’ve been able to easily adapt that content to work with Flare, as well as handling the other imports.
- All these changes could easily have resulted in chaos, but Flare supported us here, too:
- We can easily adapt the structure of our documentation, and this is automatically reflected in our site menu when we next build the HTML documentation.
- Flare’s open, text-based approach means that the overview of our offering is created and presented using easily adaptable standard HTML and CSS.
- Users can easily find the information they need by searching across the site.
- Flare’s open approach has also allowed us to easily integrate additional tools into our workflow. With our previous tool, this would not have been possible, and would have required workarounds and separate processes, adding complexity.
- From a visual point of view, Flare has helped ensure that we present the documentation well. All our documentation, whether relating to traditional products or new services, is presented in a unified visual identity, reflecting Avaloq’s brand. While this was possible with our previous tool, the process of updating the templates was more involved and allowed less flexibility in shaping the look of the output.
- Flare’s ability to produce multiple output types means we can be agile and adaptive in our user offerings and review processes. Combining this with the use of conditions gives us all the flexibility we need for our output, all from a single source.
- Every step in our workflow is now quicker: importing content, loading and editing topics, and building output all happens faster with Flare.
- With our previous CMS, new colleagues in the team required considerable training before starting to work with the tool. Flare’s user-friendly UI and project structure has allowed us to speed this up considerably–ramping-up new starts now takes less than half the time it did with the old tool.
- This ease of use and the project model have allowed us to open up the tool to some users elsewhere in the company, meaning that they can write source material directly in Flare for review and inclusion by the technical writers. This also reduces the time to provide documentation to clients, which is particularly important where product updates are being rolled out frequently.
Value for Money
There are a number of ways in which using Flare saves us money compared to our previous solution:
- The license fees are significantly lower than for our old CMS.
- We have further lowered the total cost of ownership because we no longer need so much specialized infrastructure around our tool. Instead, we can leverage other technologies that are deployed at Avaloq:
- Instead of a database that has been specially set up for our CMS and requires a specific schema, we can keep our documentation in the same repository that our developers use for their code.
- We no longer require a second database to store our PDF documentation and a special front end to make it possible to find the documentation. Instead, we have integrated this search into our Flare-produced HTML 5, and simply serve files from our web server.
- We can run Flare on machines across Avaloq. The specialized nature of the previous CMS meant that it could only be run through a separate virtual machine, which required specific maintenance.
- We can do more, quicker: these efficiency gains have been a significant factor in our team’s successes over the last five years.
What About the Users?
All of these things help us when we’re writing the documentation, which is great – but ultimately the most important question is: does it benefit our users? Here, too, the answer is very positive. We believe that Flare has helped us to maximize value for our clients:
- We push updates to our documentation site several times a day instead of uploading a batch of PDF documents once a week.
- Our faster processes mean that we can provide information more quickly and turn around updates faster.
- It’s much easier for users to find and consume the information they need:
- They can use full-text search to find the information they need, instead of having to identify the right keyword or narrow down a list by topic or area and then scroll through a list, hoping to find the right PDF.
- Users can consume the information in their preferred format. Responsive HTML 5 means they can go directly to the specific piece of information that they need, while seeing its context from the menu, breadcrumbs and links. Those who find the traditional PDF format easier to handle are still able to access that.
Switching to Flare has allowed us to keep the features that we valued from our structured DITA solution – but Flare’s greater flexibility and ease of use, together with the ability to easily import content in a variety of formats, mean that we can deliver better documentation, faster. Flare’s open, standards-compliant architecture gives us a good platform on which to build and further enhance our offering to clients.