Case study: Revamping the Paytm developer section into a dev network
Documenting why and how we moved to documentation as code concept instead of a heavy design oriented developer portal for our Payment Gateway product
WHY?
We believe that there is a difference between the way developers look at things VS the way a non dev looks at things.
Below are our observations that should mostly hold true for any product company:
- The product portal has one area meant to attract customers. (Business owners , CxO etc)
- And other area for showing how to integrate that product with customer’s existing business. (Engineers/developers/Integration teams etc)
A decade ago, if you were able to woo point 1 users, you were quite sure that product will sell. However, the case is totally different nowadays. Startups are rising and point 1 and point 2 category users are mostly the same and guess what: If you fail to attract point 2 category users: there is a high chance that your product might not sell because of lack of ease and clarity in integration.
At Paytm, we also run a vertical specially designated towards encouraging the young talent and budding entrepreneurs to Build for India. You can follow us here for latest updates. We did a survey in that forum and found that most of devs were finding it difficult to follow the steps mentioned there. And we did more surveys with in house and other devs and took a call to renovate our developer network to fix this problem once and for all.
HOW?
Our new developer portal is built on JAM stack and follows the documentation-as-code principle. Following are our core ingredients:
1. Gatsby
2. Markdown files
3. i18n
4. Minimal design
5. Opensource
Why Gatsby?
Follows the JAM stack, GraphQL, built on top of ReactJS, huge and growing developer community, built with existing and familiar web dev tech. The closest alternative that we found on similar stack was Docusaurus. However the customisation support like sidebars etc at this point (Aug-2018) is limited.
Why Md files and not HTML?
The idea is to equally allow developers and non developers to participate in our network. Any one can easily suggest or send PRs to update our documentation. This encourages a sense of ownership, teamwork and a constant feedback is after all the key to perfection.
Not to forget, we plan to open source our developer portal for anyone to extend and even add more pages in ways making it easier to follow and integrate.
Why i18n?
Well, I don’t think I need to add anything here. :)
Why minimal design?
Because as a developer myself, when I land on a developer portal, I will be more interested in clear and crisp steps without getting distracted towards high end animations and visuals. PLUS we had the backing data for this from the surveys we did in our Build for India forum.
Why Opensource ?
Developers are a core strength of any company. With this portal we are opening up channels where devs across the world can contribute to the ever growing Paytm community. I believe each one of us has a unique idea in form of different plugins, integration channels etc and by opening our portal to public we are taking the first step to collaborate. Here is our Git repo.
Feel free to collaborate!
Feedback?
We are always open for innovation and improvements. If you have any suggestions on any of our products, feel free to reach us or issue a PR or raise a bug/improvement.
Behind the scenes
I believe innovation comes automatically when you are driven by a will to solve real world problems and an awesome team who shares your vision. Thanks to Shani, Mohit, Aditya and Naman for turning this vision into a reality.
Free Goodies
We built a simple starter pack for anyone interested to kickstart a project using the above mentioned tech philosophy. Download here.
