18 Jun

Technical Documentation to Understand Midtrans Product and Integration

by Rizda Prasetya
Merchant Integration Tools & Support - Tech Lead at Midtrans

4439Views

Midtrans is a payment gateway service that offers payment solutions which most of its products are related to technical stuff. Thus technical documentation becomes one of the most crucial parts of Midtrans. Easy-to-understand technical documentation is needed to help merchants understand how to use Midtrans products from end-to-end, even if the merchant is not a technical person.
 
Since 2016, our technical documentation page has no significant changes in terms of structure and appearance. So far, we have only focused on updating content based on the latest information. As Midtrans features and products are growing, our technical documentation also needs updating due to its outdated appearance and no longer intuitive structure. It is also validated based on the feedback we got from discussions with merchants. Of course, we need to make significant updates to make it easier for our merchants to understand Midtrans products and integrate Midtrans which will also support their business development.
 
“We must learn what customers really want.” - Eric Ries, based on The Lean Startup.
 
Based on the feedback we received, such as frequently asked questions from merchants, discussions, and our research in understanding merchant needs (of course, the main goal is to make it easier for merchants!), we implemented the following points to update Midtrans technical documentation.
 

Update the Content

Some merchants usually want to know more about advanced features that can improve customer loyalty or experience and grow their business. These features include saving credit/debit card numbers, recurring payments, installments, and much more. Midtrans already has these features. It's just that the documentation needs to be easier to understand. So we added sections specific to this topic to explain these advanced features in detail with examples.
 
We also added a Technical FAQ based on the technical questions we have collected during our interactions with merchants. Not only about our products, but the questions we receive also include questions about platform-specific technical topics such as deep links and web-view. We have included topics like that in the FAQ to help answer merchants who have similar technical questions.
 

Add Demos, Samples and Case Examples

We identified several types of readers who will be the audience of the Technical Documentation, which are:

• Developer: A technical person. They want a simple integration process but don't need sophisticated features. The interactive demo, interactive sample code, simple illustrations, and main explanations will surely help this audience.

• Advanced Developer: Similar to the previous type but with more in-depth technical knowledge and have more complex business requirements. Usually, these merchants have businesses that are already enterprise-scale or advanced tech startups. This type of audience needs content such as a description of advanced features, sample code repository, sequence diagrams, Postman collection, technical and API references.

• Business user: The owner of a business or managerial and has no technical knowledge. They want to explore Midtrans products, looking for potential business value that can be used to develop their business. This type of audience will be helped by business case studies, the benefits of features, and product comparison tables.

• Non-technical merchants: MSME business owners, social sellers (those who sell through social media), or sell using e-commerce platforms. This audience will need business case studies, the benefits of features, no required technical features, plugins, and instructions for integration with e-commerce platforms.

To meet the needs of each type of audience, we have added the above relevant items to the technical documentation.

Increase Information Discoverability

As content increases, the documentation becomes too dense and makes it difficult for readers to get the information they want. So we need to strike a balance between documentation that must:

• Complete enough for an audience who wants to understand the information in detail, but also

• Simple enough to be easy to understand for audiences who want to understand the information quickly and easily

It is not easy. It is like balancing between writing a complete encyclopedia yet having to be as simple as a storybook. We need to restructure the content hierarchy as well as the sidebar. We prioritize the discoverability of key information content that merchants need to be on top of to make it easier to reach.
 
We also need to re-categorize the content on the main page to make the main content discovered yet still adding advanced feature content in relevant areas. So, merchants could find information about advanced features that they can utilize for their business.

Update the Technicals

Technically, the main problem we found was that the writing and publishing process was time-consuming, and the frameworks we used were quite outdated. The writing format we used is quite complicated, the build process is time-consuming, and the deployment is semi-manual. That is an obstacle that our writers are facing in writing and adding the content. We need to pile the content first, and then the deployment process can be done on a weekly to monthly basis. A relatively slow process!
 
The solution was that we chose a more modern and simple framework to make it easy for writers to add content. Then we improved our infrastructure pipeline by improving the Continuous Deployment (CD) process. The result is that now the process of writing to deployment can be done quickly within minutes, and the writing format is also relatively simple. Of course, this will make it easier for us to continue to add and improve documentation regularly. “Release early, release often.” according to the popular philosophy of Eric S. Raymond in the software development approach.
 
The simple format and codebase that we publicly host on Github also make it easy for other teams or external communities to help write our documentation content (yes, audiences can contribute too!).
 
We also integrate hosting providers with Content Delivery Network (CDN) that optimize and accelerate load-time when audiences open the web from their web browsers. Combining with Single Page Application (SPA) framework, now navigation between web pages becomes very fast (almost instant). Previously, the total load-time was around 500-1500 milliseconds, but now it is 200-450 milliseconds.

Now the documentation is quick and easy to write yet quick and easy for audiences to access. Win-win solutions!
 

Update UI Appearance (User Interface)

At the same time, Midtrans is also doing brand refreshments. It is a perfect time for updating the appearance of our technical documentation. We also blend the UI appearance with the main website and Midtrans products and optimize for comfortable reading.

We also observe the current UI trend, namely the dark mode. Yes, dark mode is now happening where many things around us adopt dark mode! Therefore, we added a dark mode display feature to our technical documentation UI for those who prefer more comfortable reading with a dimmer display.
 

We Listen and Improve Ourselves, To Make Your Business Integrate Easier

In the process of rolling out documentation updates, of course, it does not happen all at once, but over several months through the beta phase, early feedback, and migration phase. Until finally fully migrated at the end of 2020. With these improvements and updates, we hope that merchants can more easily understand products and integrate with Midtrans products.
 
However, this is not the end of our efforts to improve the merchant experience in using Midtrans products. We realized that there is still room for further improvement in terms of our documentation and products. We hope to be able to continue to develop it so that businesses in Indonesia will keep #MantapMelangkah
 
If you have any criticisms and suggestions for our documentation, please do not hesitate to let us know here. Because as Ben Horowitz said in the book The Hard Thing About Hard Things, “Until you make the effort to get to know someone or something, you don’t know anything”.