During a recent company hackathon, our team was tasked with enhancing the documentation for the Steampipe plugin SDK. The Steampipe system, known for its robust capabilities, is built using Go and its components are published on pkg.go.dev. The version of the documentation we were working with at the time was primarily an autogenerated list of functions and types, which, while comprehensive, often left users without sufficient guidance on how to effectively utilize those resources. To bridge this gap, we had also provided supplementary guidance on the steampipe.io website.
Our challenge during the hackathon was to seamlessly integrate this guidance into the generated documentation, transforming it into a more user-friendly resource. For developers looking to create a Steampipe plugin, the typical tasks include defining the plugin, creating the plugin entry point, and defining the first table. These tasks inherently rely on various functions and types. However, while comments associated with these functions can enrich the autogenerated documentation, they often lack the broader context necessary for a clear understanding of the development process.
In our quest for improvement, we sought inspiration from existing documentation practices. Steampipe’s lead developer, Kai Daguerre, pointed out the absence of a comprehensive overview section in our documentation, a feature he had found beneficial in the documentation for pgx, a Go driver for PostgreSQL. This observation highlighted a crucial opportunity: by incorporating a high-level overview section, we could provide users with a clearer understanding of the entire plugin development workflow.
As we restructured the documentation, we focused on creating a cohesive narrative that guides users through the plugin development lifecycle. This involved not only enhancing the existing autogenerated content but also embedding practical examples and clear explanations of how to perform key tasks. By the end of the hackathon, our goal was to transform the documentation from a mere catalog of functions into a comprehensive guide that empowers developers to leverage the Steampipe plugin SDK more effectively, ultimately fostering a more vibrant community of contributors and users.