Although I have experience in developing several Steampipe plugins, my knowledge has been limited to the fundamental aspects of the plugin SDK. I have faced challenges, like many others, in comprehending the more advanced functionalities of the SDK. During our annual company hackathon in 2022, I engaged in a week-long sprint dedicated to enhancing the SDK’s documentation. This collaborative effort involved working closely with various team members, including the lead developer of Steampipe who authored the SDK. Despite our endeavors resulting in an intriguing essay on literate programming in Go, the overall impact was not significant.
Since then, I have delved into numerous plugin codes, both reading and writing them. However, I continued to feel uncertain about my proficiency in understanding, applying, and articulating various essential patterns. I firmly believe that leveraging LLM assistance would have notably enhanced the outcomes of our 2022 documentation sprint. While we cannot replicate that specific experiment, I embarked on another attempt with the support of Unblocked, a novel LLM-backed tool tailored for developers. This tool focuses not only on code composition but also on code comprehension. As Dennis Pilarinos, the founder of Unblocked, articulates:
“You’re almost always inheriting a code base that’s been around for a long time, so the hard part isn’t writing the code to implement the feature or fix the bug. It’s trying to understand why the application works the way it does, who the best person is to talk to, when these changes were introduced, and contextualizing all that to move forward.”
Unblocked has the capability to analyze your code repositories, akin to Sourcegraph’s Cody, and additional related materials such as your website, product documentation, GitHub discussions, and Slack conversations. This amalgamation of information facilitates a service known as context assembly. Drawing inspiration from Jack Ozzie, the co-creator of Groove, a knowledge management platform, Unblocked aims to streamline the cognitive load that software teams encounter.
My encounter with Unblocked presented an opportunity to revisit our 2022 documentation sprint armed with a tool that could have immensely benefited us earlier. One of our objectives was to enrich the documentation with examples of SDK idioms, accompanied by references to the source code where these examples are contextually situated. Unblocked’s proficiency in locating such examples emerged as a pivotal advantage during this reevaluation. For instance, when seeking instances of plugin code integrating a List function with a Hydrate function, a conventional code search proved futile due to the ubiquitous nature of the terms “List” and “Hydrate.” However, Unblocked efficiently addressed this query:
“Where’s a good example of List + Hydrate?”
In response, Unblocked provided a detailed example from the steampipe-plugin-aws repository, illustrating the symbiotic relationship between the List and Hydrate functions in Steampipe plugins.
This distinctive search approach signifies a shift towards pattern identification rather than mere keyword matching. Tools adept at recognizing and pinpointing such patterns within a document corpus hold the potential to revolutionize knowledge management within the software domain and beyond.
Chris Wiggins, in a discussion on Ben Lorica’s Data Exchange, reflected on the evolution of AI, emphasizing its roots in pattern recognition, formerly known as machine learning. Ward Cunningham, the initiator of the Portland Pattern Repository, elucidated the essence of patterns in design problem-solving, underscoring their role in forming interconnected languages that facilitate the synthesis of diverse solutions.
As I endeavored to elucidate the patterns inherent in the Steampipe plugin SDK and its associated plugins, Unblocked not only facilitated the discovery of exemplary patterns but also aided in their explication. Leveraging existing source code comments and web content, I applied the principle of Ask for choral explanations to solicit diverse interpretations of these patterns. By seeking explanations from multiple LLMs like ChatGPT, Claude, and Gemini, I aimed to capture a comprehensive understanding suitable for a varied audience.
Moreover, Unblocked’s feedback on my draft sections provided valuable insights and suggestions, some of which I incorporated verbatim. This collaborative dynamic with Unblocked during the rewriting process underscored the potential for AI to serve as a co-author, fostering a synergistic partnership that enhances the overall quality of the content.
In stress-testing the documentation, I encountered instances where Unblocked’s responses required verification and refinement. By challenging the tool with queries expected to be addressed in the documentation, I could assess the completeness and accuracy of the content. This iterative process not only validated the documentation but also highlighted areas for potential enhancement.
In conclusion, the integration of LLM-powered tools like Unblocked into documentation workflows holds immense promise in augmenting code comprehension and documentation quality. The seamless amalgamation of code and contextual information through such tools can significantly elevate the effectiveness and efficiency of documentation endeavors, paving the way for a more informed and enriched documentation ecosystem.
