API documentation is an essential resource for developers for effective and efficient collaboration. It eases product integrations by presenting a clear understanding of API contracts, their purpose, and the behavior of an API from a consumer perspective. Documentation is a vital component in the development ecosystem.
At Druva, we have a constantly evolving ecosystem of platform components that cater to multiple teams within the company. Versioned documentation is paramount for a smooth and efficient development and integration experience.
How does adequate documentation help development?
Documentation serves as a shared language among teams collaborating with each other. It provides detailing of the APIs with respect to their behavior, expected input variations, and output. Establishing this contract earlier in the development cycle help integration efforts by allowing individual teams to leverage the shared API interfaces to mock and test their code effectively. With this practice, teams can work concurrently and dependency bottlenecks can be minimized.
Single source of truth
A project involves multiple contributors — developers, architects, QA engineers, and managers. A crisp and clear API documentation keeps everyone on the same page.
While debugging an issue, developers can quickly refer to the API documentation to validate the expected behavior, input/output, and error-handling details. Versioned documentation helps developers understand if there have been any changes to the API contract.
API documentation helps the onboarding of new developers by serving as a reference guide. It provides just the right amount of information to get started. In combination with design documentation and knowledge transfer sessions, new developers can dive deeper into the architecture.
How do we maintain and render documentation?
Initially, we used godoc (now deprecated) to generate static pages after the creation of tags and would render these HTML pages through a simple web server. As part of a hackathon project, we decided to help ourselves to make our documentation infrastructure user-friendly, feature-rich, and seamlessly integrable with CI/CD. This prompted us to delve into various open-source alternatives, such as pkgsite, and experiment with different rendering methods — from local files to proxies. Ultimately, we found the ideal infrastructure that perfectly suited our requirements.