Golang Packages: Documenting In-House Development

Introduction

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?

Cross-team collaboration

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.

Debugging

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.

Developer onboarding

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.

Go Proxy

A Go Proxy is an immutable repository of versioned Golang packages. It offers benefits to ease dependency management; however, for the purpose of this blog, we use it to download modules from the git remote repository.

pkgsite

Pkgsite provides a set of tools for generating and rendering documentation through a web server in combination with cache/proxy or module files. We are utilizing the following pkgsite components.

Worker

The Worker takes in the input of a target package with its tag. It downloads the tag from a preconfigured Go Proxy and saves the symbols in a local postgreSQL database.

Frontend

Frontend works with a web server and postgreSQL database to render the documentation.

Key features

1. Global search across all packages

2. Cleanly rendered documentation for exposed symbols

3. Symbol Index for every package

4. Convenient option to add an overview of the package through a doc.go file

5. Easy navigation across interfaces and internal data structures, types

6. Versioned documentation facilitated by a tag listing page for each module

What does the developer have to do?

The one-time infrastructure will ensure that tag creation triggers the documentation pipeline. However, the developer’s responsible for writing meaningful and detailed comments on exposed API/Interface declarations, request-response structures, and constants. Optionally, every package can contain a doc.go file which can be used to add verbose or high-level detailing of the package like its responsibilities, and usage guide as required.

References

1. Guidelines for documenting Go code

2. Configuring a Go Proxy with Athens

3. Understanding pkgsite ecosystem