Accelerating Deployment of Open Source Workloads Using Executable Docs in Copilot

Users sometimes feel that the Azure documentation isn't reliable, accurate, or relevant to the their particular application, doesn’t consistently span across services and OSS as E2E Solutions, and doesn’t consistently match their expertise level and their products' complexity.​ This is the problem we are tackling with Exec Docs and we'd love your feedback on the approach.

Executable Docs (aka Exec Docs) make documentation testable and actionable, simplifying the evaluation and adoption of services on Azure. They cleverly do so by transforming standard markdown into interactive, executable learning content, allowing code commands within the document to be run step-by-step or “one-click”. In the cloud, this translates to automated deployment/maintenance of Azure resources using CLI commands. In the world of copilots, this translates to them being able to reference a corpus of rich, tested documentation and understand what the user wants/deliver it to them better!

Exec Docs are powered by the Innovation Engine, a transformative open source CLI tool that enhances the entire documentation lifecycle by powering the execution and testing of these markdown scripts and by integrating with CI/CD pipelines, which ensures that documentation is always up-to-date and error-free. This means that companies can rely on their documentation to be accurate and executable, reducing the time and effort required to maintain and update it. The Innovation Engine empowers teams to focus on innovation and execution rather than troubleshooting documentation issues.

On November 19, 2024, a demo on Exec Docs was presented at the Microsoft Ignite conference in Chicago, USA! The product was showcased as part of a theater session that myself and Mitchell Bifeld conducted: Accelerate deployment of open source applications with Copilot in Azure. The purpose of this session was to show how companies can leverage Exec Docs, Innovation Engine, and Copilot to accelerate the execution of their company’s workloads today. Since the actual session wasn’t recorded, the pre-recorded demo version can be found at Ignite 2024 Exec Docs Demo Final.mp4       

As part of the 12-minute demo, the team showed the following to their audience:

• Discovery and Deployment: How to seamlessly discover and deploy the workload of their choice (setting up an AKS cluster) using a guided experience provided by the Microsoft Copilot in the Azure portal
• Customization: How to customize the Executable Doc from the first step by downloading it and adding monitoring onto it (our open source project Inspektor Gadget) with little knowledge on how to set it up using GitHub Copilot
• Testing: How to validate the outputs of the AI in real time using Innovation Engine in our CLI
• CI/CD Pipeline: How to leverage and run a GitHub Action workflow (the template for which was provided by Innovation Engine), which would create a CI/CD pipeline that uses Innovation Engine to prevent errors in documentation from merging and keeps them up to date, making our Exec Doc testable

The visibility around Exec Docs was not just limited to this demo as we shared it as experts at the Linux for Azure booth in the subsequent days. There, we were not only able to get feedback from/answer questions of Linux on Azure customers/enthusiasts but also share our progress with them and get their hands dirty with running Exec Docs as part of our Event in a Box initiative.

An example of a great customer insight was an System Integrator (SI) that came to meet us afterwards and wanted the ability to add private, custom documentation to the Azure Portal and have it load their documentation within our guided experience as an Exec Doc. This would also be useful for SIs who could then just link their GitHub Repo/other documentation source with this feature and then share the Portal deeplink containing the Exec Docs from that source with customers.

Another customer wanted a tailored experience for Exec Docs as Labs. This experience would include the following: load prerequisites needed for the lab beforehand automatically, prompt user to enter commands in the guided Portal experience during the lab and compare their answers to the actual output (using the expected_similarity functionality of IE) that would show how close/far they are to the ideal command, and allow them to download their scripts to be able to continue local testing/customization afterwards (this exists in the current experience as “Download source file”)

Moving forward, we expect customers to have the opportunity to run their documentation as a guided experience in our Portal setup, offer these docs as labs for vendors to teach best practices for deploying open source workloads on Azure, and many more!

To get started, customers can try out one of our Azure Exec Docs via deeplinks in Microsoft Learn articles. As for those who wish to incorporate these functionalities for their custom workloads, they can install the Innovation Engine repo in their local machine’s CLI and start there!

We look forward to our customers using Copilot to try out Exec Docs and hope they integrate Exec Docs into their company’s documentation so that it never goes out of date and that anyone can use it to accelerate the execution of their workloads not in hours or days, but in minutes. This is the future of Azure – where learning, deploying, and customizing what the user wants is simpler than ever before.

Please reach out via comments or messages with any questions.