Introduction
At its core, the Freshworks developer platform strives to offer a streamlined app-building experience for our developers. We are committed to bring developer-friendly tools to you based on the valuable insights and feedback we seek and receive from our vibrant community. We understand and acknowledge the frustration when critical resources are scattered, fragmented, or challenging to navigate. We recognize that such obstacles can hinder your app development journey and divert your focus from crafting a polished final product. We also continuously attempt to democratize our processes and systems such that we can set up a highly accessible contribution system for all our resources - co-owned by us and our community.
Developer documentation and developer enablement content (such as tutorials, how-tos, sample apps, and so on) are the guiding map that helps you to solve coding challenges, explore product and platform capabilities, and turn your app ideas into real solutions. Our erstwhile developer portal(s) were a bunch of dispersed resources. Though the content quality was something that our developer community always appreciated, the mechanism offered for consuming the content was convoluted. Also, as we grow, we find the pressing need to open our content portals to diverse contributors from our own product teams and from the community as a whole. Our past tooling fell short of meeting the requirements necessary for a co-owned authoring and contribution system.
Today, we present to you our indigenously-built Unified Developer Website that aims to offer the best possible user experience and an authoring/contribution system that is not far from the coding environment that our contributors are used to.
What’s New?
Well, everything!
Check out the App SDK documents at the Freshworks Developer Docs.
At the outset, what would be visible to you is:
- A one-stop host for all developer enablement resources - docs, tutorials, how-tos, and so on.
- An expansive suite of UI components - such as smart On this page anchors, tabbed right pane for code blocks and sample codes, expanding and nested object tables to easily understand the nested attributes of (our very many) JSON files, accordions, and noticeably more components - that help you to access and comprehend content smoothly. (If you do count, you will be able to number close to 35+ custom UI components. )
- An enhanced product switching experience.
- A responsive UI that works well on your mobile device as well.
- A dark mode to view content.
- A uniform app development content across all products.
Behind the “seen”s
While what you see at our new developer site is what you have always wanted to see, we have gone a step ahead.
This is our endeavor to present a future where our developers, Freshworks engineers, technical writers, developer advocates/evangelists, and product managers can all contribute to our enablement content through a system that is aligned with a typical coding environment. Yes, a system built on the docs-as-code philosophy. A philosophy that promotes shared ownership of content by fostering an environment where documentation is delivered using the same tools as code; the same:
- Issue Trackers
- Version Control (Git)
- Plain Text Markup (Markdoc, in our case)
- Code Reviews
- Automated Tests
We have built and delivered a Markdoc + Next JS + React based Git + Markdown website. A Git + Markdown website is the de facto industry standard today for developer documentation websites. We were initially skeptical of building this system; but the release of Markdoc in 2022 changed things for us. Markdoc inherently packages Stripe’s experience building world-class documentation websites; we aptly leveraged it.
Our architecture choices allow us flexibility in creating and customizing content layouts through custom front-end components. The infrastructure needs of a separate CMS are eliminated in our system, making it highly maintainable. The tooling provides provisions to run reviews and obtain instant local feedback during content authoring. The content is hosted on a mono (Git) repo, facilitating information chunking and single-sourcing across all content resources. Our website deployment is managed through an efficient Jenkins-based CI/CD pipeline with rollback ability. We also have an efficient Jenkins-based CI/CD pipeline for website deployment with rollback ability
We plan to put out a blog soon on what exactly we have built and how we have built it. Do keep a watch out for the blog.
What’s Next
Next quarter, we intend to deliver phase 2 of our unified website. You can keep an eye out for,
- The availability of all our tutorials and other developer guides, with intuitive search-and-filter capabilities, as part of the website.
- Integrated search capabilities.
- Enhanced component designs.
- …and more.
Shortly, all access to our old content will be redirected to the new website. We are working on this as we speak.
Meanwhile, check out the unified developer website and let us know your feedback.
Your appreciation gives us immense joy; your improvement suggestions give us the scope to better our system. Keep them both coming.
