Generate Code Documentation Using Amazon Q Developer

Writing software documentation can feel like a time-consuming task, but it is vital for sustainable development and maintenance. Clear and concise documentation serves as an invaluable asset with three critical purposes: it streamlines team collaboration, accelerates developer onboarding, and simplifies maintenance tasks. By integrating documentation into your development workflow, you can boost team efficiency and maintain a sustainable codebase.

Research on AI-powered development tools has shown transformative potential in the software development lifecycle, reducing documentation time by up to 50% and decreasing repetitive coding tasks by 30-40%. Yet development teams still face a persistent challenge: maintaining current documentation without slowing down development velocity. Teams often skip creating or updating documentation due to the time-consuming nature of manual maintenance, leading to missing or outdated content.

Amazon Q Developer addresses these challenges by automating the documentation process, helping teams collaborate more effectively and maintain up-to-date documentation. This generative AI-powered assistant automatically creates a README file that evolves with your codebase. It goes beyond basic text documentation by generating visual diagrams to illustrate your system architecture. Though AI tools have limitations with complex, multi-file operations and specialized codebases, implementing Amazon Q for Developers can enhance your documentation workflow.

Solution Overview

This blog post demonstrates how to generate a README file using Amazon Q Developer with Visual Studio Code. Using Bob’s Used Books, an ASP.NET Core 6.0 MVC application example, I will show you how the Pro tier‘s advanced documentation features automatically create detailed documentation for your codebase. The sample application implements a monolithic n-tier architecture, providing an ideal environment to showcase documentation generation across different application layers.

While I focus on Pro tier features in this walkthrough, it is important to note that Amazon Q Developer offers two service levels. The Pro tier, which I’ll explore in detail, provides advanced documentation capabilities, while the Free tier provides basic features accessible to all users. For a comprehensive comparison between the Free and Pro tiers, see our detailed comparison guide at Amazon Q Developer Pricing.

Figure 1: Architecture diagram of ASP.NET Core 6.0 MVC application example 

Important note: Generative Artificial Intelligence (AI) services, including Amazon Q Developer, are non-deterministic and may produce different results with each use. While these tools provide valuable assistance, you should carefully review and validate all generated content against your actual implementation. The quality of output depends on input clarity and context, human oversight is essential for ensuring accurate and appropriate documentation.

Prerequisites

Before implementing Amazon Q Developer in your development workflow, you’ll need to ensure you have the necessary accounts and tools in place.

• An active Amazon Web Services (AWS) account.
• An AWS Builder ID login controlled by your organization.
• Amazon Q Developer integrates with several popular Integrated Development Environment (IDE). You can use Visual Studio Code, JetBrains IDEs, Visual Studio or Eclipse IDEs (Preview). Refer to our compatibility guide at Supported IDEs and available features.

Part 1: Generating sample documentation with Amazon Q Developer

Amazon Q Developer helps you gain deeper insights into your development framework by analyzing your codebase. It automatically identifies and documents key components of your system, such as feature specifications and creates detailed technical documentation outlining the repository structure. This walkthrough shows you how to create well-structured documentation with Amazon Q Developer using Visual Studio Code as the IDE.

1. Open your project and locate Amazon Q Developer in the IDE.

Figure 2: Locate Amazon Q Developer in the VS Code activity bar on the left

2. In the chat window, enter /doc in the Amazon Q Developer chat window to activate the documentation feature.

3. You’ll see several documentation options – for this demonstration, create a README file by selecting Create a README and confirming with yes.

4. After confirmation, Amazon Q Developer begins analyzing your codebase. In this example, it has identified the project bobs-used-bookstore-sample-main.

Figure 3: Generate README file by entering /doc and selecting Create a README

5. The README file generated by Amazon Q Developer provides documentation covering key application features, web application flow and AWS infrastructure components.

Figure 4: Amazon Q Developer analyzes the project and generates a README file

6. To refine the README file, provide more context or requirements. Amazon Q Developer will adjust the output to match your needs. If you’re satisfied with the output, press Accept.

Part 2: Update sample documentation with more details

After generating your initial README file in Part 1, Amazon Q Developer offers several ways to enhance and refine your documentation. Let’s explore 3 methods to create more comprehensive documentation for your project:

a. Adding Component Descriptions

b. Analyzing Application’s Database Structure

c. Creating Visual Diagrams

2a: Adding Component Descriptions

To add detailed information about key functions and features to your README file, follow these steps:

1. In the chat window, select Update an existing ReadMe followed by Make a specific change.

Figure 5: Update README file by selecting Update an existing README and Make a specific change

2. Enter the following prompt:

Generate a concise description of the key functions and features of the application. Include details for Bookstore.Web/ (UI management, API endpoints, and client-side logic), Bookstore.Domain/ (business logic, domain models, and key entities), and Bookstore.Data/ (data persistence, database interactions, and repositories).

3. Based on your requirements, Amazon Q Developer updates your README file by adding detailed explanations of each project component’s functions and features.

Figure 6: Updated README file showing detailed function and feature documentation

4. Review the highlighted modifications Amazon Q Developer has made to your documentation. You can request more refinements until the content meets your needs. Once you’re satisfied with the updates, select Accept Changes to save the modifications to your README file.

2b: Analyzing Application’s Database Structure

To gain insights into your application’s database architecture, Amazon Q Developer can analyze and document your database schemas. Here’s how to enhance your documentation with database-specific information:

1. Enter the following prompt:

Identify and add information of the database system the application interacts with and provide details on its schema, including tables and required columns.

2. Through code pattern and structure analysis, Amazon Q Developer can infer your database context without requiring explicit schema definitions in project files. This intelligent analysis provides insights about your database schema based on your application’s implementation.

Figure 7: Amazon Q Developer’s application database analysis output

2c: Creating Visual Diagrams

Amazon Q Developer helps you understand your system’s architecture through automatically generated technical diagrams, such as class diagrams, use case diagrams and sequence diagrams. Here’s how to create a visual diagram:

1. Enter the following prompt:

Add a sequence diagram to visualize the typical flow of a request through the Bookstore Web Application.

2. These visual representations complement your written documentation and provide insights into your application’s behavior and architecture. Visualizing system interactions helps identify potential design issues early in the development cycle, before they impact your production environment. The architectural diagrams translate complex technical concepts into accessible visual formats. This shared visual understanding streamlines technical discussions and accelerates decision-making processes across your organization.

Important note: The generated diagrams reflect Amazon Q Developer’s interpretation of your code structure and may require validation against your actual implementation.

Figure 8: Sequence diagram generated from Amazon Q Developer’s analysis

Best Practices

Start your Amazon Q Developer implementation with a structured, phased approach. Begin by selecting smaller, well-defined projects to identify improvement opportunities and build a foundation for broader implementation. This methodical approach helps your team adapt gradually while maximizing the tool’s benefits.

During code reviews, use Amazon Q Developer to analyze updates and generate documentation about technical modifications. Share these insights through your team’s collaboration tools to facilitate clearer discussions and better understanding of code changes.

This implementation approach ensures smooth adoption while maintaining productivity. As you use Amazon Q Developer, gather team feedback and adjust your processes accordingly. Remember to validate all generated content against your actual implementation to ensure accuracy and relevance.

Conclusion

Amazon Q Developer’s generative AI capabilities transforms documentation through automated codebase analysis and README file generation. Teams can reduce manual documentation work, streamline onboarding, and enhance code comprehension. This automation helps developers focus on innovation while maintaining up-to-date documentation, improving productivity and resource allocation.

Get started with Amazon Q Developer today by installing it on your supported IDE and generate your first README file in minutes. Take it further to observe how Amazon Q Developer automates documentation tasks and simplifies your development workflow. The journey to more efficient documentation management begins with this first step, enhancing your team’s productivity and collaboration.