Chronicle: A story of building technical documentation for GO-DATA

By Ravi Suhag

At GO-JEK, the Data Engineering team is responsible for crafting reliable data infrastructure across all of GO-JEK’s 18+ products. We aim to provide disproportionately large advantages to GO-JEK over competitors by making data available, accessible, reliable and actionable at scale.

Our GO-DATA platform allows teams to build on our products to develop innovative solutions, creating new opportunities for our customers and expanding what’s possible.

Why do you need an internal product website?

In the real world, when we buy a product, it comes with a quick guide or some other form of documents which help you get going with the product. Without these documents, we’ll have to learn how to use the product leveraging solely on the ‘trial and error’ method — which is not a pleasant user experience at all.

We support and build data products for more than 15 internal teams. Our target audience includes product managers, developers, operation managers, and business analysts. Hence:

• We faced problems in communicating what the Data team is working on and what is next in our product lineup.
• It was getting harder to make clear that there is something missing in their life and that is our product/service.
• We found ourselves handling support requests on a daily basis, consuming a lot of our core development time.
• Worst of all, for developers, data engineering became equivalent to Firehose (data consumption toolkit). For business analysts, we were Dagger team (data aggregation toolkit), for OMS teams we were fronting team. (data publishing toolkit) and so on. Find out more about our architecture here.

At this point, we had an intensive wiki but it did not suit our needs anymore. We needed a better solution, something that reflects our products well and delivers clear communication on how to getter started and deep dive without any need for a Data Engineering team.

Process:

We are a team of full stack human beings and believe at our core that a developer’s job is not just writing code. We own the full product cycle and are as responsible for sales and adoption as our product manager. Which means, we took it into our own hands to design the entire product website. We know the product best so no one else can communicate it better than us.

Research and Planning:

With Chronicle the goal was to make people get started with our products and deep dive when they are comfortable, without any support from the Data Engineering team. To understand what to expect from Chronicle, we started by talking to teams about how they approach and use products, preparing flows around targeted audiences and categorizing our products accordingly.

Content:

Almost any product has some kind of documentation — might just be a warning or brief usage instructions. But for more complex products, there has to be a solid user guide which requires constant update and maintenance.

This usually demands a dedicated documentation team working constantly with developers. Despite the fact we have more than 10 internal data products, we wanted to make technical documentation as much part of our daily work as writing code.

Everyone is responsible for clearly articulating and documenting the use case for every feature we release. Our documentation follows the same CI/CD pipeline as our products.

Design:

We designed Chronicle to provide both a fantastic user experience while adding efficiency to internal processes through effective documentation and reusable components.

We have defined components for system architecture design, narrative design, and print materials. Now, we can take those components and start building out on top of them. You can see these components in use in our blogs.

Data infrastructure at GO-JEK - 5 min read

.

Gojek5 min read | Mar 12, 2018Share:

Data engineering design system includes:

• UI Kit with 20+ reusable and customizable components for system architecture design
• Design Library and templates for narratives design. e.g. XKCD styles narratives
• Brochures and kits for print materials.

Development:

Before deciding to design and develop Chronicle from the ground up, we looked into many tools available e.g. docsify. Despite the fact there are many tools out there, none seem to fit our requirement. We needed:

• A data-driven product website which can pull data from our metadata services and stay updated.
• New content should autofill custom defined layout structures.
• Markdown support with the extensibility of including custom HTML based style wherever needed.
• Indexing and product categorization should be driven from markdown content files.

We built Chronicle using Gatsby — React powered static generator, giving a good place to start and still allowing us to implement our custom structures and design.

Delivery:

We launched Chronicle, the Data Engineering product wiki, to ensure that there is a better understanding of our platform across the organization as well as easier, centralized access to developer documentation. Chronicle was no less than a product for us and we went ahead and followed the full protocol: from printing brochures, user showcases and personal interactions.

Adoption:

It took us 2 weeks to bring Chronicle to the teams and has reduced the need for support time by almost 80%.

“Damn, it’s like one of the best documentation I have ever seen” — Renata, Business Intelligence

“Looked at the documents, very well compiled” — Vinay

Our work to make our documentation a thorough, living document, will never be over, but feedback like this helps us know we’re on the right track.

Conclusion

Documentation when done right, can help people get excited about a product. If you believe in the progressive disclosure, you understand that documentation is a part of your product experience.

Chronicle acts as a source of truth for everyone about what Data Engineering has to offer, giving everyone a shared language and making them partners in the stewardship of our product toolkit.

If you like what you’re reading and interested in taking on some of these challenges with our team, do check out our engineering openings at gojek.jobs. If none fits the bill, mail us. We always have room for talented folks. As always, would love to hear what y’all think 🖖