Codat
Introduction
Codat Docs is a one-stop shop for documentation and API references that are designed to enable developers to get started in minutes. It has everything our developer community needs to build powerful applications for small businesses with financial data provided by Codat. We're experts in how applications interact with the software SMBs use, so our clients can focus on what makes them superior.
This year, we have completely overhauled our documentation and API references. We replaced our out-of-the-box solution with a custom one that caters to our continuous growth. We introduced a new navigation structure that gives a developer a clear path from understanding Codat’s core concepts to launching their fintech solution. Finally, we manually rebuilt our API references and the underlying OpenAPI specs, moving away from codegen practices and implementing documentation-driven development practices within our engineering teams. This has led to more accurate, reliable, and significantly more detailed API references.
Why nominated
BEST API REFERENCE DOCUMENTATION
Within the DX community, we have been observing a trend of increasingly turning to code-generated API references associated with the perception that this ensures accuracy.
However, we have been codegenning our API reference for many years, and have actually seen the exact opposite: manual creation of an OAS specification ensures more accurate and significantly more detailed API reference content.
We chose to craft our documentation and API reference manually to deliver an improved developer experience. This is underpinned by document-driven development practices implemented within our product and engineering teams. Teams prepare the documentation upfront, before then implementing the associated functionality. In turn, our dedicated developer experience team helps guide our best-in-class RESTful API design, reviewing proposed API designs and ensuring consistency throughout our APIs and schemas.
This has allowed us to create an incredibly detailed API reference full of robust descriptions down to the field level and exact endpoint functionality, extensive code examples in multiple languages, integration-specific requests and responses, default and example values, and examples of success/failure responses. Every endpoint can be tried out within the API reference itself. This helps our customers understand the API behavior in great detail and see the bigger picture of how the components of our API tie together to make something even more powerful.
This level of detail in our OAS has also unlocked our new client library SDKs, and we are constantly adding to the scope of languages covered. We believe these SDKs are critical for a great developer experience as they bring the API details into the context of the developer’s IDE and in their language of choice.
Our dedicated developer experience team works tirelessly to provide more interactivity, guided examples, and demo apps and tutorials that showcase Codat’s capabilities in action. This enables our customers to learn about a specific scenario or use case, and understand exactly how Codat can be used within their own applications.
Finally, we have open-sourced our docs and made contributing to them as easy as possible, using git to support a docs-as-code workflow.
BEST VISUAL DESIGN
Visual design at Codat is driven by our beautiful and accessible design system, the single source of styles, patterns, and assets we use within our landscape, born from our detailed telemetry. It puts legibility first, uses color strategically, prioritizes accessibility (AA), and helps us ensure consistent and coherent UX across all of Codat’s ecosystem.
This now applies to our documentation too. We built our own bespoke docs portal from scratch using Docusaurus, which allowed us to reimagine and fully customize our readers' visual experience in line with our design system. We use color strategically, employ clean and consistent styles, and use a clear hierarchy of UI elements and content, providing our readers with an effortless reading experience.
We focused on structuring the documentation pages appropriately, from correct text hierarchy to the use of diagramming, screenshots, and videos. This is critical for legibility and enables the developers to detect key details on the pages and understand their layout faster. React components supported by the platform also allowed us to build interactive navigation and content elements.
All of this is supported by various graphic assets that are consistent across the documentation, providing a sense of familiarity when moving from page to page, and enabling readers to quickly find the concepts and guidance they need.
BEST NEW DX INNOVATION
We have made many bold changes and improvements to our API reference and documentation in alignment with our ambition of being a leader in developer experience.
For example, we chose to move away from code-generated API references and instead create our documentation and API reference manually to maintain our best-in-class RESTful API design. This allowed us to create an incredibly detailed API reference full of robust, clear descriptions down to the field level and exact endpoint functionality, extensive code examples in multiple languages, integration-specific requests and responses, default and example values, and examples of success/failure responses.
We have also implemented document-driven development practices within our product and engineering teams, and have our dedicated developer experience team reviewing proposed API designs to ensure consistency throughout our APIs and schemas.
We have enhanced our documentation with Cochat, our innovative conversational tool powered by GPT 3.5. While our documentation is thorough and detailed, Cochat has the ability to join disparate content together to solve users' more complex problems faster and help them better understand how to leverage our capabilities for building integrations.
Communication in natural language also allows us to gain a new level of insight into the problems our community encounters so that we can continuously improve our documentation and product.
To enhance the developer experience, we focused on building out the Codat developer community. Our users raise questions, provide suggestions, and share their experiences using GitHub discussions. We have even open-sourced our documentation so that anyone can contribute to our documentation (from small changes using the GitHub UI to supporting the docs-as-code workflow). Finally, we introduced Office Hours - our regular drop-in sessions that anyone could attend to get support and expert advice on building a solution with Codat.
We also work to support a variety of learning styles our developer customers might have. We offer a quickstart guide that is aimed at both devs and non-devs, and video guides for visual learners. For a more robust approach, we built out a learning journey that starts with Codat’s basic concepts, goes on to configuration details, and graduates to the use of our API. We also constantly produce more demos, guides, and tutorials that showcase Codat’s capabilities in action. This enables our customers to learn about a specific scenario or use case and see how Codat can be used within their own applications programmatically.
