A discussion with Pierre-Olivier Saint-Joanis,
Quality Manager at HPS.
Historically, how was the production of documentation organized?
In the past, the documentation team consisted of 3 people, managing a documentation corpus of several hundred documents. There are 3 targets for this content. First, the users of our 14 solutions: installation and configuration guides, technical notes, user manuals, interface and functional descriptions. Then, developers: hundreds of files describing the design of the software, the data model. Finally, the decision makers at our customers’, for whom HPS Pre-Sales and Marketing teams manage separately PowerPoint documents.
Until recently, we would mainly produce Word documents, transformed into PDF and distributed via Sharepoint. Thus, by connecting to Sharepoint sites, our customers could find both product documentation and specific project documentation – each implementation involves a significant amount of personalization related to the customer’s activity, locally applicable regulations, or interfaces with their own systems.
What drove you to structured documentation?
I am responsible for quality, and the documentation has recently been integrated into my scope, with the aim of improving the user experience when searching for information and for the right document. One of the main problems that we have identified is that there are many variants out there for each of our products.
This forces us to maintain many different versions of the same documentation. On one hand because the product is evolving, and all customers do not have the same pace of upgrading their software. On the other hand, because each customer has specific needs, and these must of course be documented and kept up-to- date. Therefore, we can quickly end up with a dozen different versions of the same document, for the same software.
Another key topic is audience. The same subject can be treated from a marketing or pre-sales perspective, from a functional (user-driven) point of view, with screenshots and a manual, or from a technical point of view for engineers in charge of the implementation or maintenance of the system. This plurality of audiences had no elegant solution in our existing documentation system, forcing us to create, duplicate and maintain different and redundant types of documents, without consistency, and without the possibility of switching from one audience to another.
About HPS
HPS is a global provider of payment solutions for payment issuers, acquirers, processors, mobile network operators, distribution as well as national and regional switches around the world.
PowerCARD, HPS’ software suite, covers the entire value chain of payment by enabling innovative payments through its open platform that allows the processing of any transaction, initiated by any mean of payment, from any canal. PowerCARD is used by more than 400 financial institutions in more than 90 countries.
HPS has been listed on the Casablanca Stock Exchange since 2006 and has offices in major business centers (Africa, Europe, Asia, Middle East).
So you initiated a structured documentation project?
The needs described above were in perfect alignment with the concept of structured documentation. I therefore decided to set up an internal project with a request for investment in software and resources that would allow us to reach the goal of moving into the industrial age, choosing the DITA model for authoring and publishing.
The project, from the initiation to the beginning of the realization has matured for a year.
How did you approach the project?
First, we had to preserve our „business as usual“: continue to
deliver for our customers, maintain the existing content. So we did not change everything, at least at the beginning. The team of 3 people continued to work with their tools and techniques. They were of course kept informed and involved. And we deployed a new team dedicated to the structured documentation project which was able to take its marks without disrupting the existing processes. We very often kept the other team up- to-date on the progress, and from the beginning we were committed to training them 100%. Now the integration is going well, despite a radical culture change. The logic of structured documentation is almost opposed to traditional writing logic. You really have to touch the benefits to be convinced.
From an organizational point of view, we approached things „from both ends“. On one hand the writing tools, including conversion of existing content, from Word to DITA. And on the other hand, starting from the user experience: definition of metadata, taxonomies, synonyms, groups and permissions. We were able to set up procedures, for example create a taxonomy consistent and obvious to all users.
Everything was done in a very iterative way. We would frequently review our progress so that the two subjects converge. This is how the taxonomy was enriched, modified, standardized. Many times we have tested, published, deleted, added a source, etc. This proved to be a key factor for the success of the project.
The enriched taxonomy proved to be a key factor for the success of the project.
According to which dimensions is the content organized?
Among the metadata we use for organizing content, we can list: solution (among the 14 products we offer), functional component, and possibly a subset of this component. This taxonomy allows, for each article, to identify the product and the context in which it is used.
We also use metadata to categorize each document by its editorial type: user guide, installation documentation, training support, functional description for example.
In addition, we classify the nature of the document (structured or unstructured), author, software version, component and topic version, reference, and other metadata such as the target audience.
All these metadata are proposed as filters (facets) to the users so that they can refine their search.
Finally, to meet the specificities of each client project, we use a final tag, somehow upstream of all others. This tag, labeled „Customer“, contains the value „Product“ if the subject applies to a product and therefore potentially to all customers, or the name of the customer if it is a specific document that only the named customer must to be able to access. This tag is a key one for our access rights system.
The tools
Componize is a DITA CMS that optimizes the writing, management and translation of documentation throughout a company, and facilitates the contribution of domain experts.
Fluid Topics captures all technical content, regardless of format, and effortlessly delivers a dynamic documentation portal.
Componize and Fluid Topics are integrated to facilitate the publication of technical content, without losing its rich structure.
How did your new team get access to business expertise?
With a freshly recruited team, this access was indeed essential. We did hire a tech writer who did not know our domain but who was proficient with DITA. She had to take ownership of 200 documents, segment into topics, and load into our Componize CMS, all this without mastering the topics covered by these documents.
She worked in pair with a business analyst from the existing team to whom she could ask any question. Together, they were able to factor contents, and to reduce the size of the documentation by one-third. Then they defined glossaries of definitions to avoid repetitions of recurring concepts, such as „account“, „card“, „merchant“, etc. We have thus moved from 600 definitions to 90 harmonized, centralized, consistent and reused definitions.
The business taxonomy was built by first listing all the identified business keywords used in existing documents. Then we organized it in tree structure, with synonyms, specific and generic terms. This tool is very powerful for searching in Fluid Topics.
Which contents are included in your documentation corpus?
As of today, the heart of this corpus is mainly focused on documentation for our clients: written in DITA with Componize and published through Fluid Topics, representing more than 6500 topics.
We are gradually adding content for developers, which is currently stored separately, and documents produced by HPS Academy (our internal training team). Ultimately, we are also considering adding presales and marketing presentations.
For APIs, we have a separate portal and are working in parallel on a Swagger doc for our JSON APIs. It will be necessary to have these 3 solutions converge.
The team in charge of commercial proposals could also be interested at some point.
About structured documentation
„Documentation structured with DITA XML brings many benefits, but it is a change that must be well prepared. We must be especially mindful of change management and involve the relevant teams as soon as possible – writers and contributors. The choice of tools is also important. With simple and standardized user interfaces, Componize’s DITA CMS has contributed to the rapid adoption of new practices.“
Who are the users of the documentation?
At first, we opened the portal to our 300 internal engineers. The success was immediate, because of how easy it becomes to target the right information in a large corpus. The feedback from these users is excellent.
We then opened access to our customers, who can efficiently search and access with an incredible simplicity, in view of the volume and complexity of our documentation. They can use Fluid Topics’ rich functionality to post comments or build personal books.
The use of the content differs according to the phase of the customer deployment. During the setup phase that lasts from 6 months to 2 years, customers need to try out, understand the operation and how the software is configured. They will use technical descriptions, user guides, interface files. Then, during the operation phase that will last 10 to 15 years or more, the only documents that will be read by the customers will be the user guides – frequently at the beginning, then periodically during the ramp-up of a new operator.
We opened the portal to our 300 internal engineers, the success was immediate.
How has content production been impacted?
In view of the first results, a team of development engineers has volunteered to change the way they produce code documentation. They understood what we were doing, the interest of DITA and semantic tags. They elected to produce their docs with Componize and to publish them with Fluid Topics. A tech writer is responsible for proofreading and minor corrections (standardization, choice of the proper metadata).
Following this pilot, we organized a presentation of the new platform to all engineers, and other teams wanted to get started. It changes quite dramatically the way we produce that documentation since until now, the developers coded, made demonstrations to technical writers who then produced documentation. Developers did not write much content.
Our goal is to increase productivity and to integrate the development of documentation into the code production chain. Each program segment will be documented at the time it is written, by the person who codes it. If we succeed in changing mentalities internally, it will be a major breakthrough.
From structured doc to commercial content
Building a commercial proposal is actually similar to building structured documentation: a lot of copy & paste, customization to the specifics of the customer, which ultimately requires a huge amount of design and customization.
By adopting the methods of the structured technical doc, the time savings could be very significant. In particular, we are looking at how to use Fluid Topics’ Personal Books concept to aggregate sub-sections into a near-finalized document.
To what extent has this new documentation impacted the business?
One of the strongest impacts is the ability to turn documentation into a sales pitch. The previous version of the documentation already reassured the client because he could see that the software was real, not just mockups, but he still had to receive the documentation (or an excerpt) by email and this would delay the answer to certain difficult questions.
When a prospect asks for a feature, we can now say instantly „yes, we have it and that’s how it works“, with documentation as a supporting tool. With Fluid Topics, the pre-sales engineer can type in a few keywords in the search engine and immediately access the desired answer. The articles that address the topic are presented, and facets make it possible to filter the product and version concerned.
HPS therefore benefits from augmented pre-sales, with all their knowledge, plus everything they do not know but is contained in the documentation.
The documentation becomes a key element of the commercial success of our products!
Quick facts
14 software solutions
100+ product developers
200+ developers working on customer projects
6 technical writers
6500 topics
Check out the HPS Website
Want to read this case study offline or print it?
You might be also interested in
Talend delivers consistent documentation through metadata-driven publishing
Mediametrie Redesign Their Documentation Publishing Process for a Better User Experience
