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

How and why we designed one of the best internal product wiki

At Gojek, the Data Engineering team is responsible for crafting reliable data infrastructure across all of Gojek’s 18+ products. We aim to provide disproportionately large advantages to Gojek 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 that helps 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 the Dagger team (data aggregation toolkit), for OMS teams we were the 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 much responsible for sales and adoption as our product manager. This 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.

Photo credit: Deepak Sasikumar

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 that 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. Components can then be reused across all our blog posts, documentation and newsletters.

Data engineering design system includes:

  • UI Kit with 20+ reusable and customizable components for system architecture design
  • Design Library and templates for the narrative 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 that 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 the 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 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 🖖

--

--

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store