SimCorp, Global Investment Management Solutions Provider, Uses MadCap Flare to Ensure its User Documentation is Ready for Agile Development and the Cloud

Increasingly, investment managers rely on SimCorp and its integrated, best-in-class investment management solutions to get a complete picture of their business, improve investment decisions, and gain operational efficiencies. Clients now include more than 190 of the world’s leading financial institutions, including asset managers, insurance companies, pension funds, fund managers, wealth managers, sovereign wealth funds, and asset servicers.

Over the decades, SimCorp Dimension^® has evolved to become a world-class, front-to-back investment management system featuring a long line of integrated solutions and associated services. The SimCorp technical documentation team supports this system with a suite of online Help topics and user manuals online and in PDF files. The team relies on MadCap Flare to keep their documentation and its processes modern and stable as SimCorp moves to an agile methodology and the cloud.

Selecting Flare for Large-Scale Topic-Based Authoring

Back in 2011, the SimCorp Dimension documentation system had become unmaintainable: The tool environment consisted of Microsoft^® Word to write monolithic user manuals and the Microsoft^® HTML Help Workshop to create a .CHM deliverable. The components were bolted together by error-prone helper applications and scripts, which only one or two developers could maintain. The massive .CHM file included more than 100 user manuals and 100,000 windows and field Help topics. Keeping the user manuals up-to-date was impossible for the small team of technical writers; the content contained gaps, redundancies, and inconsistencies.

Putting strategy before tools, the documentation team decided to move from writing front-to-end sequential user manuals to a task-oriented, topic-based information architecture. The architecture is built on a subset of elements from the topic-based Darwin Information Typing Architecture (DITA) standard, a sort of Lightweight DITA variant pre-dating Lightweight DITA. This corporate standard ensures that the documentation can reflect all common use cases.

The tool selection process cast a wide net to include Help authoring tools and content management systems. MadCap Flare prevailed over more comprehensive solutions, thanks to its unique fit: Flare provides all required output formats. Its paradigm of topic-based authoring supported the new information architecture, and the easy import of legacy Microsoft^® Word documents ensured that the conversion of content would succeed. Additionally, the accessible American Standard Code for Information Interchange (ASCII) format of all files in Flare supports a maximum of control and customizing of the Help processes by the documentation team.

“One of the things I love most about Flare is that the files, including topics, snippets, tables of contents, and JavaScript, are so transparent that we can go in and change whatever we want to achieve almost anything,” Mads Sorensen, SimCorp lead technical writer, observes. “We really appreciate Flare’s extensibility, which supports us in creating our own extensions to support our software requirements, and that’s what has made it the perfect tool for us.”

Revamping the Documentation Process with Single Sourcing

With MadCap Flare in place, legacy manuals were imported from Word to be restructured and streamlined. There was now a single source for every information and task. Updating user manuals had become much easier and faster. Thanks to the topic architecture, the work could easily be distributed and traded between writers.

“With Flare, writers from separate teams can collaborate on the same topic, whether they’re aware of it or not, and it will come out seamlessly in one tone and style,” Sorensen explains.

MadCap Flare's single sourcing capabilities helped to provide the contents of previously page-based user manuals as an integral part of the online Help for the first time. With Flare's powerful references and relationship tables, the documentation team created a true web of a Help system that let users enter at any point and navigate quickly to the desired information.

MadCap Flare's rich feature set also supports SimCorp's complex documentation process for dozens of writers and reviewers:

• Topic status, author, and localization languages are reflected in topic File Tags, which are used to control and process the topics along the workflow.
• On-demand building and publishing of user manual updates is automated in batch targets.
• Downloadable PDFs of the Help contents are integrated in the HTML5 build by using build events.

Just how well MadCap Flare supported the Help and its processes was borne out by two recent challenges to the documentation team: going to agile development and moving the Help system to the cloud.

Adapting to Agile Methods

In 2015, SimCorp started to transform a product division of 500 people from waterfall to agile methods. The main challenge for the documentation team was to release the Help more frequently and to add incremental documentation.

“We went from two to four major releases per year, and we adopted two-week agile sprints, which meant we needed to update our documentation at least every two weeks to sync with the development cycles,” recalls Kai Weber, SimCorp lead technical writer.

“We also needed to think about how to support over 50 agile teams while still creating and maintaining a documentation set,” adds Sorensen.

This is where the DITA-based topic architecture pays off, according to Weber: “The fact that Flare’s topic-based authoring functionality, which we were already taking advantage of, works perfectly under the new agile environment has made the transition a lot simpler and smoother.”

For a more agile distribution of tasks, the documentation team uses a custom Kanban board in Flare. Process information is maintained right in the Flare projects by setting up a Flare table of contents (TOC) as a Kanban board where tasks are moved through nodes called Backlog, In writing, In review, In editing; Published, and so on.

“Thanks to the flexibility of Flare, we were able to innovate and use TOCs to have Kanban boards right inside Flare and keep an overview of all features and their topics,” Weber notes. “This has been a blessing, since we can mimic agile project management without needing a second tool.”

The standardized process enables the documentation team to assign writers to work on documentation tasks, even outside the projects they usually work on. Additionally, MadCap Flare’s integration with Microsoft^® Team Foundation Server (TFS) for source control allows writers to more effectively synchronize their efforts on projects.

Ensuring Continuous Delivery

Agile teams and writers share documentation user stories, which drive the creation of topics. Developing content incrementally means that topics can be amended and reviewed until they are ready for release. Publishing such incremental topics internally makes feature progress transparent and serves as a feature preview throughout the company.

"We’re now able to produce incremental release notes of what’s coming up in future releases," Weber observes. "Any colleague can view those notes and know exactly what’s coming in the pipeline. This is a huge benefit because everyone in the company gets a better, faster understanding of what product development is working on.”

MadCap Flare's publishing automation allows continuous delivery by supporting builds and publishing at least nightly or even instantly, Sorensen says: “We can now build three huge outputs on each build server in just four hours, which is only made possible by how quickly Flare can build the big documentation suite. This fast documentation cycle is key because it means we can quickly close the whole feature and move onto the next one in the pipeline. It’s extremely important for our agile teams to have this workflow.”

Getting Documentation Ready for the Cloud

The next challenge is to provide the same extensive documentation suite for SimCorp's cloud solutions, which have increased performance demands on the Help system. A post-build event to minimize the size of the Help package shaved off about 12% of the traditional tri-pane delivery with similar gains in the time to load and search. But the real performance boost came with a shift to MadCap Flare's recent Side Navigation output. The most recent micro-content feature will help to further integrate solutions and Help content in the cloud user experience.

“Flare helped us make future-proof decisions in 2011, which still work today and allow for organic and seamless evolution as our requirements evolve,” Weber observes. “Since then, a lot has changed in the product division around us: We went from waterfall to agile development. We changed our project management tool; we’ve added an extra programming language, and we’re just now changing our versioning tool. But the one tool that has stayed the same is MadCap Flare, thanks to its flexibility and robustness and to the forward-looking design decisions we made eight years ago.”

Weber adds, “The beauty of MadCap Flare is that in terms of the set-up, software, and processes, it has us totally covered. We wouldn’t have been able to keep in step with the company’s evolution without it.”