Using Amazon Q Developer to Turn My Code into a README

Hey Builders! As a software engineer, you’ve probably been there. Documentation is the last thing on your mind. Especially in fast-paced environments like big companies, it often feels like an afterthought. But skipping it creates technical debt, and let’s be real. A project isn’t truly complete without docs. We can’t tell people “just read the docs” if there aren’t any! I’ll admit, I’m guilty of this too. When I get excited to build and deploy something, I sometimes forget to document what I’ve done.

Take my project, Mycologeek.com. I’ve poured tons of time into this site, but its README? Embarrassing. It’s a title, two lines, and a typo. Here’s the commit for proof! You’d be right to expect better from me, and I’m sorry to disappoint! So, while exploring Amazon Q Developer in VS Code, I decided to put it to the test. Could it read my code package and whip up a decent README? Spoiler: I’m mostly happy with the results. Here’s how it went.

The Experiment

I fired up VS Code, opened my Mycologeek project, and summoned Amazon Q. My prompt was simple. “Read my code package and write me a README.” After a moment, Q delivered a markdown-formatted file. Here’s what stood out on the first naive run.

The Pros

1. Organized Markdown Formatting
   The output was clean and structured, with headers, bullet points, and code blocks. It looked like a proper README right out of the gate.
2. Nailed the Project’s Purpose
   Q described Mycologeek.com as “A website dedicated to mycology and technology, featuring a blog system with categorized posts about mushrooms and tech topics.” Spot on! It grasped the core idea without me spoon-feeding it.
3. Captured Key Features and Most of the Tech Stack
   It listed features like the blog system and the technical stack (Python, AWS Services), but it didn’t initially grok that it’s a Flask app. Not every feature made the cut, but it got the big pieces.
4. Quick Technical Summary
   Q highlighted the tools powering the site, which gave me a solid starting point to build from.

Amazon Q did warn me it wouldn’t catch everything and would prioritize what it deemed important. Fair enough. It missed my temperature monitoring platform and photo gallery, which I can add later. Oddly, it mentioned the fonts I’m using. Fonts? Really, Q? I chuckled at its priorities, but overall, I had a basic README I could commit today and polish later.

The Cons

No tool’s perfect, and Q’s not an exception. Here’s where it stumbled.

1. Security Slip-Up
   You can’t just dump AI output into a public space without a double-check. Q initially included my AWS API endpoint in the README. That screamed security risk so I asked a follow-up. “Is this safe to share?” Q backtracked, offered security tips (like using environment variables), and helped me scrub sensitive details. Lesson learned. Always review AI suggestions!
2. Missing Installation Details
   Q didn’t realize Mycologeek is a Flask app at first, so it skipped installation and deployment instructions. I followed up with “This is a Flask app. Add instructions.” Boom, it delivered solid steps. Installing Python, setting up a virtual environment, running pip install -r requirements.txt, and launching with flask run. Perfect after a nudge. I can only imagine that Q will get better at this.
3. Markdown Confusion
   Q tried to show my project’s file structure, but the markdown broke in spots. On subsequent runs, Q would stop writing Markdown intermittently, especially when trying to draw directory structures/file trees. It was easy enough to go and format the rest since most of the content was generated.
   As for the file tree: I could copy-paste and fix it, but honestly, I don’t think a README needs a file tree… it’s just more work! You’re already in the repo 80% of the time. Why repeat it? Q’s output glitch isn’t a dealbreaker (it’ll probably get fixed), but it suggested something I’d skip anyway.

Putting It All Together

After the initial README, I refined it with a few more prompts. First, I clarified it’s a Flask app for those instructions. Then, I said. “Combine everything, but don’t expose sensitive info like API endpoints.” Q delivered a revised version. It’s not flawless. I’ll tweak a few lines. But it’s commit-ready. Here’s the gist of what I got (simplified for this post), check out the whole thing in Github!

# Mycologeek.com

A website dedicated to mycology and technology, featuring a blog system with categorized posts about mushrooms and tech topics.

## Features
- Blog system with categorized posts
- Flask-based web application
- Hosted on AWS infrastructure

## Tech Stack
- Python
- Flask
- AWS (S3, EC2, and more)

## Installation
1. Clone the repo: `git clone <repo-url>`
2. Set up a virtual environment: `python -m venv venv`
3. Activate it: `source venv/bin/activate` (Linux/Mac) or `venv\Scripts\activate` (Windows)
4. Install dependencies: `pip install -r requirements.txt`
5. Run the app: `flask run`

My Takeaway

With Amazon Q Developer, I went from a sad two-line README to a functional one in minutes. It read my code, captured the essence of Mycologeek, and gave me a foundation I can refine. Sure, it needed some babysitting (no API endpoints, please!), but it saved me from staring at a blank page.

I also feel that it was able to provide me an objective document without considering my ego and bias. That might not be an issue for you, but for me it allowed me to just get it done without having to overthink the effort I put in. So what if I spent 20 hours on a bug, does the end user need to know? Probably not. Q just dismissed all of my fee-fees and gave me some output.

WARNING!!! As developers, we’ve got no excuse to lag on docs anymore. Amazon Q in VS Code is like a co-pilot that kickstarts the process. It’s not perfect, but it’s a huge step up from “I’ll do it later.” Check out the updated README on my GitHub. Try Q for yourself. Your projects deserve it!

WriteMe,
– Ryan