Iterative, AI-Powered Documentation with Templates & Inline Edits! - Quack The Code

This is a submission for the Amazon Q Developer "Quack The Code" Challenge: Crushing the Command Line

What I Built

I built qmims (short for "Q, Make It Make Sense!"), a powerful command-line interface (CLI) tool designed to automate and revolutionize the often tedious process of creating and maintaining README.md files for software projects.

The Problem: Every developer knows the importance of a good README, but keeping it comprehensive, up-to-date, and well-written is a constant challenge. It's easy for documentation to become an afterthought, leading to outdated or incomplete project information that hinders collaboration and user adoption.

The Solution: qmims tackles this problem by leveraging the AI capabilities of Amazon Q Developer CLI. It acts as an intelligent orchestrator, using Amazon Q to:

• Analyze your project's codebase, structure, and dependencies.
• Automatically generate complete README files from scratch.
• Guide README creation using built-in or custom templates.
• Perform precise, AI-driven edits to existing READMEs based on natural language instructions embedded directly within your Markdown files.

With qmims, developers can significantly reduce the time spent on documentation, ensure consistency, and produce high-quality READMEs that truly "make the project make sense" for everyone. It turns README maintenance from a chore into an AI-assisted collaborative process.

One of the coolest parts? The README.md for qmims and its documentation website was generated using qmims itself, powered by Amazon Q!

Demo

While the documentation website provides comprehensive details, here's a visual walkthrough of qmims in action:

Let's break it down!

First, we see the qmims project with a minimal README.md:

We then run qmims generate (which defaults to auto mode). qmims checks for the Amazon Q CLI and prompts if it needs to overwrite an existing file.

Once confirmed, qmims starts the q chat session, and Amazon Q begins its analysis of the project. You can see Q detailing its steps, like reading the directory structure and package.json.

After analysis, Amazon Q outlines the comprehensive README structure it has generated based on the project's content.

And here's the README.md file automatically generated and populated by qmims using Amazon Q!

Now, let's showcase the edit command. We add a simple instruction comment to the end of our README.md file to add a "Made with Love" section.

We run qmims edit. qmims starts q chat, which finds and processes our embedded instruction.

Amazon Q then modifies the README.md file directly to incorporate the requested change, adding the new "Made with Love" section. It also confirms what it did in the terminal.

These screenshots walk us through how qmims leverages Amazon Q Developer CLI to both generate comprehensive READMEs from scratch and make precise, instruction-driven edits, streamlining the entire documentation process. For full details and advanced usage, please visit the documentation website!

Code Repository

You can explore the full source code for qmims from the public GitHub repository:
https://github.com/wSoltani/qmims

Due to a temporary 24-hour restriction on npm after an initial publishing attempt, the package qmims might not be immediately installable via npm install -g qmims. However, the tool is fully functional and can be easily run from the source code available in the repository. The npm package will be published as soon as the restriction is lifted (about 20 hours after this post).

Update: the package is now live on npm!

How I Used Amazon Q Developer

Amazon Q Developer, specifically the Amazon Q Developer CLI (q chat), is the core AI engine that powers qmims. My tool acts as an intelligent orchestrator for q chat to perform sophisticated documentation tasks. Here's how:

1. Project Analysis & Content Generation (auto mode):

   • qmims invokes q chat within the context of the user's project directory.
   • It sends high-level prompts like, "Analyze this project and generate a comprehensive README covering typical sections."
   • Amazon Q then uses its understanding of code, file structures, and common project patterns to generate relevant content for sections like Overview, Tech Stack, Installation, and Usage.

2. Template-Driven Generation (template mode):

   • qmims provides q chat with a Markdown template structure (either built-in or user-defined).
   • It then prompts Q to fill in the content for each section defined in the template, based on its analysis of the project. This allows for structured yet AI-generated documentation.

3. Instruction-Based Editing & Generation (instruct mode with qmims edit or qmims generate --mode instruct):

   • This is where Amazon Q's agentic capabilities truly shine.
   • Users embed natural language instructions within HTML comments (e.g., <!-- qmims: Rewrite this section for clarity. -->) in their Markdown files.
   • qmims parses these instructions and crafts specific prompts for q chat, providing the instruction and relevant file context.
   • Crucially, qmims then instructs q chat to directly propose and (with user permission) edit the Markdown file. For example, Q might say, "I will replace lines 25-30 with the following improved text. Proceed? (y/N)".
   • qmims manages this interactive dialogue, relaying Q's proposed changes and the user's approval back to q chat.

4. Context Management:

   • qmims ensures q chat is always operating in the correct project directory.
   • It can also dynamically instruct q chat to consider specific files (e.g., package.json, or the README.md being edited) when necessary to improve the relevance of Q's output.

Tips & Insights from Using Amazon Q Developer CLI:

• Agentic Power is Real: The ability of q chat to understand a task, propose file modifications, and then execute them (with permission) is incredibly powerful. This was key to the instruct mode in qmims.
• Context is King: The more relevant context q chat has, either from the project directory or specific files added to its context (using /context add ), the better and more accurate its output. The Context section in the Amazon Q CLI documentation was very helpful.
• Prompt Engineering for CLI: Crafting effective natural language prompts that work well when sent programmatically to q chat required some iteration. Keeping prompts clear, concise, and action-oriented yielded the best results.
• Handling Interactivity: Programmatically managing the interactive prompts from q chat (especially permission requests for file edits) by capturing stdout and writing to stdin of the child process was a core challenge but essential for qmims's workflow.
• Iterative Refinement: For complex documentation, instructing Q to generate or edit in smaller, iterative steps often works better than one massive prompt. The instruct mode in qmims is designed for this.
• No Need for an AWS Account (Builder ID): The fact that developers can use the full power of Amazon Q Developer CLI with just a free AWS Builder ID is a fantastic enabler for tools like qmims and for this challenge.

Building qmims was a fun exploration of how an AI assistant like Amazon Q Developer can be orchestrated through its CLI to create a genuinely useful automation tool that goes beyond simple code generation. The process of using qmims to help generate its own documentation and part of its website's content was a particularly rewarding experience, showcasing its practical utility firsthand.