DEV Community: Wassim Soltani

An Interview is a Conversation You Can Lead. Here's How.

Wassim Soltani — Sun, 14 Sep 2025 20:00:03 +0000

Funny how we spend years learning to code, but no one really teaches us how to handle an interview. I've had a lot of people reach out for advice recently, from juniors to experienced engineers, and the pattern is always the same: they're worried about being put on the spot.

The fear of getting hit with a trick question or not knowing an answer is real. But having been on both sides of the table, as an interviewee and as the one doing the hiring for my company, Blueblood, I've learned that a successful interview isn't about having a perfect score.

It's a structured conversation, and you can be the one to guide it. I've put together my playbook for how to prepare, stay in control, and actually nail it.

The Game Plan

Do Your Homework (No, Really)
Prepare Your "Cheat Sheet"
Talk About the Money
It's Your Conversation

Step 1: Do Your Homework (No, Really)

The single biggest mistake developers make is shotgun-blasting applications and then scrambling to figure out what a company does five minutes before the call (if at all). The goal of research is to determine if you are genuinely excited about the opportunity and to distinguish yourself from the hundreds of other applicants.

Your research should start the moment you decide to apply. Here's your checklist:

1. The Official Website (The Source of Truth): This is your first stop.

Values/Mission Page: Do their values resonate with you?
Products Page: What are they building? Do you find it interesting?
Blog/News Section: What are their recent announcements or technical challenges?

2. LinkedIn & Glassdoor (The Unfiltered View):

Company Profiles: Get a feel for their size, recent posts, and company culture.
Reviews & Salary Data: Read employee reviews and check for self-reported salary ranges for similar roles.

3. The Final Google Search (The Catch-All):

Search for news articles, press releases, or any other public information that might have slipped through the cracks.

The outcome of this phase should be a simple document of raw notes. This document is your material for the next step.

Step 2: Prepare Your "Cheat Sheet"

Your research document is a messy brain dump of raw information. You don't want to be frantically scrolling through that during the call. The goal of this step is to condense that research into a clean, one-page "cheat sheet" that you can glance at to keep you focused and confident.

This shouldn't be treated as a script. It's a set of talking points organized into a few essential sections.

1. Your Tailored Introduction (The 30-Second Pitch)

The first question is often "Tell me about yourself." This isn't an invitation to read your resume out loud. They already have it. It's your chance to deliver a concise, powerful pitch that proves you're the right person for this specific job.

A good way to structure it is in 3-4 sentences:

Who you are: "I'm a fullstack engineer specializing in..."
Technical Alignment: "...with experience in React and TypeScript, which I saw was a key requirement for this role."
Value Alignment: "...I was really drawn to your company's mission to [mention something from your research], and I'm looking for a role where I can build products that have a real impact."

2. "Why I'm a Good Fit" (Your Talking Points)

Here's a helpful way to organize your thoughts. Try a simple two-column list. On the left, list the top 3-4 requirements from the job description. On the right, map one of your projects or skills directly to that requirement.

Company Needs	My Experience
Experience with React	Built a full admin dashboard with React, TypeScript, and Zustand.
AI/ML Interest	Developed a multi-tenant AI chatbot on the Cloudflare stack.
Cares about UX/Design	My portfolio and projects use a clean, modern design system (shadcn/ui).

This helps you have specific, evidence-backed answers ready when they ask about your skills.

3. Salary & Logistics (The Practicalities)

It's always a good idea to have your numbers ready. It shows you're a professional who knows their worth:

Their Range: £60,000 - £100,000 (from your research)
My Desired Range: £80,000 - £90,000
My Walk-Away Number: £75,000
Question for them: "What is the envisioned salary range for this position?"

Remember, this is a normal part of the process. It's not greedy to talk about money; it's why you're there.

4. "My Questions for Them" (Show Your Interest)

Always have questions prepared. It shows you're engaged and genuinely interested, and it's your best chance to find out if the company is the right fit for you.

Here are a few good starting points and what they help you achieve:

"What are the biggest technical challenges the team is currently facing?"
- Why you're asking this: It shows you're a problem-solver, not a ticket-closer. You're already thinking about how you can provide value.
- What it helps you learn: It gives you a real preview of the job's day-to-day challenges and helps you decide if they're problems you'd be excited to work on.
"Could you tell me more about the day-to-day responsibilities of this role?"
- Why you're asking this: This signals that you're thinking practically about how you would fit into the team and its workflow.
- What it helps you learn: It cuts through the job description jargon. You'll find out if the job is mostly new features, bug fixes, or maintenance, and what the team's agile process is really like.
"What does the typical onboarding process look like for a new engineer?"
- Why you're asking this: This is a very smart question for a junior. It shows you're serious about getting up to speed and contributing effectively.
- What it helps you learn: The answer reveals how much a company invests in its new hires. A good answer will mention mentorship, documentation, and a structured plan for your first few weeks. A vague answer can be a red flag.

With a one-page cheat sheet like this, you'll walk into the interview feeling prepared, confident, and ready to guide the conversation.

Step 3: Talk About the Money

Sooner or later, the salary question will come up. Don't treat it like a taboo. This is a professional conversation about your livelihood, and companies expect it. Getting shy or closed off shows a lack of confidence.

Your research from Step 1 is your anchor here. Here’s how to handle it:

If the job post included a range: A great response is, "The range you posted aligns with my research and my expectations for the role."
If the post did not include a range: The best move is to let them provide the first number. You can ask confidently and politely: "I'm still learning about the full scope of the role, so I'd be interested to hear what the envisioned salary range for this position is."
If you must give a number first: Don't give a single number. Based on your research of similar roles, provide a confident range. For example: "Based on my research for similar roles in this market, I'm targeting a range of $X to $Y."

Remember, this is an initial check to make sure you're in the same ballpark. As long as your number is reasonable and based on research, it won't disqualify you. The final offer comes later.

Final Thoughts: It's Your Conversation

At the end of the day, remember this: an interview isn't a test you pass or fail. It's a two-way conversation to determine if there is a mutual fit. They are evaluating you, but you are also evaluating them.

This playbook isn't a script to memorize; it's about giving you the structure to walk in prepared and confident. Don't just hope you know the right answers. Be ready to show your value and to lead the conversation.

Be curious, be confident, and be yourself. The right opportunity will recognize your value. Good luck!

I Built a Game to Understand Fly.io's Orchestrator: flyd Operator Sim!

Wassim Soltani — Tue, 03 Jun 2025 01:02:19 +0000

I've recently been deep diving into Fly.io's infrastructure, particularly their flyd orchestration server and the superfly/fsm library that powers its stateful operations. To truly grasp the operational challenges, I built an interactive simulation game: flyd Operator Sim.

Play it here: https://flydsim.wsoltani.com/
Repo: https://github.com/wSoltani/flyd-operator-sim

🤔 Why Build a Simulation?

Fly.io's platform is impressive. Reading their insightful blog posts and their public infra-log revealed the complexities of flyd. The superfly/fsm library also highlighted their focus on robust state management.

I wanted to explore:

What kind of incidents can actually occur on a worker node running flyd?
How does an operator diagnose and respond to these issues?
What's the impact of different actions on system health and application uptime?
How do Finite State Machines (FSMs) play a role in managing complex operations like machine migrations, even if it's abstracted away from the operator in a crisis?

Building a sim felt like the best way to learn.

✨ Introducing: flyd Operator Sim!

In flyd Operator Sim, you're an on-call engineer for a Fly.io region. Your goal:

Monitor worker health (CPU, memory, flyd status).
Respond to incidents like flyd stalls, containerd sync issues, network partitions, and storage corruption (many inspired by the infra-log).
Act using tools like flyd restarts, worker drains, log inspection, and (risky!) FSM overrides.
Maintain Uptime over a simulated period.

Game Objective & Progression:
Your main goal is to maintain high application uptime across your workers for 7 simulated days. Each day lasts about 5 minutes in real time. To make things more interesting, you start with one worker, and an additional worker is added each day, up to a maximum of four, increasing your responsibilities and potential points of failure!

🎓 What I learned

Orchestration is Complex: Simulating even a part of it showed me the immense challenge of managing global infrastructure.
State Management is Crucial (and complicated): The game reinforced how vital accurate state is for flyd and why a solid FSM library like superfly/fsm is essential, especially seeing potential containerd desync issues.
Observability is Non-Negotiable: Good metrics and logs (which the game simulates access to) are critical for diagnosing issues, a theme evident in Fly.io's own infra-log.
Operational Trade-offs: The sim touches on the pressure of quick fixes versus safer, slower solutions.

🤓 Tech Stack

Built with: Next.js, TypeScript, Tailwind CSS, Radix UI (shadcn), and React Context.

💭 Try It & Share Your Thoughts!

This was a personal learning project, but I hope others find it useful or fun.

Play: https://flydsim.wsoltani.com/
Repo: https://github.com/wSoltani/flyd-operator-sim (give it a 🌟!)

What incidents should I add next? How can it be a better learning tool? Let me know!

Thanks for reading 💖

The Tiny Cat Guide to AI #4: LLM Evaluation – Is Your AI on Catnip? (Spotting Hallucinations)

Wassim Soltani — Fri, 23 May 2025 21:08:32 +0000

Welcome back to The Tiny Cat Guide to AI!

We've journeyed through Prompt Engineering, dived into Generative AI, and equipped our AI cats with a library for RAG. But what happens when our well-intentioned AI, even with good data, confidently tells us something... that's completely bonkers? 🤪

This brings us to a crucial aspect of building trustworthy AI: LLM Evaluation and tackling those pesky "Hallucinations".

To make these concepts more approachable, our trusty feline guides are back! This time, they're helping us understand how we measure AI responses and try to trick them into revealing their weaknesses:

So, what's the deal with AI "hallucinations" and evaluation, as seen by our cloud of cats?

Imagine our smart RAG cat (from Post #3) gives an answer. But did it truly understand the facts, or did it just invent something plausible-sounding from the "fluffy cloud" of data it was trained on? These inventions are "hallucinations." LLM Evaluation is how we meticulously check our AI's work, ensuring its answers are truthful and helpful, not just creative fluff. 🧐

As our visual story shows:

If one cat says "meow," did the others understand? We might count matching "meows" (like BLEU for precision).
What if a cat says "muwr?" Is that still close enough? (Like ROUGE for capturing the gist).
And what if we try to trick a cat by saying "woof woof!" – will any cats bark back? That's like Red Teaming – trying to find unexpected or wrong responses!

Why is this so critical?
We need to be able to trust our AI. For example:

My portfolio chatbot must accurately represent my experience from its RAG sources, not invent project details.
Quickplan, my AI tool for processing meeting notes, needs to generate reliable summaries and action plans, not flights of fancy based on misinterpretations.

Mistakes here undermine their value and our trust in the system.

Evaluating LLMs means tackling challenges like defining what "good" actually means (it's often subjective), looking beyond simple accuracy towards relevance and overall coherence, and dealing with the "black box" nature of some complex LLM behaviors.

Here are some key insights to guide AI towards truthfulness and robust performance:

🧠 Define Success & Measure It: Before you even start building, decide what a good output looks like for your specific use case. Is it factual accuracy? Successful task completion? User satisfaction? Use appropriate metrics, such as:

BLEU (Bilingual Evaluation Understudy): This checks the precision of AI-generated text against human-written examples by counting matching sequences of words (n-grams). It's often used to evaluate the quality of machine translation.
ROUGE (Recall-Oriented Understudy for Gisting Evaluation): This evaluates how well AI-generated summaries capture key information from human-written references by looking at overlapping word sequences, focusing on recall (i.e., how much of the important stuff was covered).

Alongside these automated scores, thorough human review is almost always indispensable.

🛡️ Stress-Test with "Red Teaming": Don't just test for expected behavior; proactively try to make your AI fail or hallucinate. This technique, known as "Red Teaming" or adversarial testing, involves crafting inputs specifically designed to expose weaknesses, biases, or edge cases in your AI's understanding and response generation.

🔗 Keep Grounding Strong (RAG Revisited): As we discussed in the RAG post, providing solid, factual context is a primary defense against hallucinations. Beyond that, explicitly instruct your LLM to cite its sources for claims or to clearly state when it doesn't have enough information to answer.

🔄 Iterate with Human Feedback: There's often no substitute for human judgment. Collect feedback on AI outputs, review them carefully, and use these insights to refine your prompts, the data the AI uses, or even to fine-tune the models themselves. This continuous improvement cycle is crucial for building robust and trustworthy AI.

📡 Monitor, Monitor, Monitor: AI performance isn't static; it can drift over time as data changes, user interactions evolve, or underlying models are updated. Continuously watch your live systems for any unexpected behavior or emerging patterns of hallucinations so you can address them quickly.

Tackling hallucinations and robustly evaluating LLMs are key to building AI we can truly rely on. It's about moving beyond just getting an AI to work, to ensuring it works well, truthfully, and reliably.

What are your go-to methods for checking AI outputs, or what's the wildest AI hallucination you've ever encountered in your projects? Share your stories and insights in the comments! 👇

The Tiny Cat Guide to AI #3: RAG – Tiny Librarians

Wassim Soltani — Thu, 22 May 2025 17:41:05 +0000

Welcome back to The Tiny Cat Guide to AI!

In our journey so far, we've explored Prompt Engineering – Directing the AI Ballet and peeked inside Generative AI – What's Inside the Magic Box of Cats?. Now, let's tackle a common challenge: how do we get AI to give answers that are not just smart, but also deeply informed by specific, relevant documents it wasn't originally trained on?

The answer often lies in a powerful technique called Retrieval Augmented Generation (RAG)! 💡

To illustrate how RAG works, I've summoned our feline friends once more – this time as diligent tiny librarians:

So, what's RAG all about, as told by our tiny cat librarians?

Imagine your AI has access to a giant library filled with specific knowledge (like all the world's tiny cat facts!).

When you ask a question (say, about "fluffy kittens"), instead of just relying on its general, pre-existing knowledge, the AI first dispatches tons of tiny librarian cats. These cats zoom through the shelves, find the most relevant scrolls of information related to "fluffy kittens," and bring them back.

Then, a super smart "reader" cat (our LLM) carefully reads these specific scrolls and uses that freshly retrieved information to answer your question accurately and contextually.

This "retrieve first, then augment the answer" approach is the heart of RAG. It helps the AI:

Stay factual and reduce "hallucinations."
Use up-to-date information it wasn't originally trained on.
Access private or domain-specific knowledge (⚠️ always be careful with data privacy).

Building AI features often means implementing RAG. For instance, I've applied it to:

My portfolio chatbot: It uses a RAG setup (leveraging Cloudflare AutoRAG) to sift through documents detailing my professional background, skills, and projects to answer your questions. You can even chat with it here to see it in action!
AI enhancements for an E-commerce platform: RAG leverages embedded product details for semantic search, enabling a more helpful Q&A chatbot and relevant product recommendations based on understanding user queries deeply.

Working with RAG has definitely had its share of "aha!" moments and tricky bits:

😵‍💫 Ensuring Retrieval Relevance: Making sure the "librarian cats" fetch the exact right scrolls is crucial. Irrelevant documents lead to poor answers.

🧠 Context Window Constraints: Fitting all the crucial info from retrieved scrolls into the AI's limited working memory (the "reader cat's" attention span) can be a puzzle.

⚖️ Synthesizing, Not Just Repeating: Guiding the AI to weave the retrieved info into a coherent answer, rather than just copying chunks verbatim, requires careful prompting.

🖼️ Knowledge Base Management: Keeping the "library" (source documents) fresh, well-organized, and accurately indexed is an ongoing task.

So, how can we guide our AI to make the most of RAG and help our tiny librarians be more effective? Here are some deeper insights that have helped me:

✅ Curate Your Knowledge Base: Quality and structure are paramount for your "library." Clear, well-written, and logically organized source documents make a huge difference. A consistent voice can also help. While some tools automatically convert files, starting with clean Markdown, for example, often leads to better results.

✅ Smart Document Design & Chunking: Think about how your information is structured. Logically separated, focused documents or sections often lead to better automated "chunking" (breaking documents into digestible pieces for the AI). Aim for chunks small enough for retrieval precision but large enough to retain meaningful context.

✅ Effective Retrieval Strategy: This is often about more than just keyword matching. Implementing semantic search – understanding the meaning and intent behind a user's query – allows the AI to find the most conceptually relevant chunks, even if the exact wording differs.

✅ Clear Prompting for Context Use: Once the relevant information is retrieved, you need to explicitly guide the LLM on how to use it. Do you want it to summarize, extract specific facts, answer a question based only on the provided text, or synthesize information from multiple sources?

✅ Iterate & Evaluate: Building a good RAG system is rarely a one-shot deal. Test it rigorously. When you get an unexpected answer, examine the retrieved chunks to understand why. This will help you refine your documents, your chunking strategy, your retrieval mechanism, or your prompts.

RAG is a game-changer for creating more reliable, tailored, and context-aware AI applications. It beautifully combines the broad knowledge of large language models with the precision of specific, targeted information.

What are your go-to RAG techniques, or any particular "librarian cat" headaches you've encountered while trying to fetch the right info? Share your experiences below! 👇

Does that cloud look like a bunch of tiny paws to you, or am I hallucinating?

Wassim Soltani

May 23 '25

The Tiny Cat Guide to AI #4: LLM Evaluation – Is Your AI on Catnip? (Spotting Hallucinations)

#ai #machinelearning #llm #learning

Comments

3 min read

The Tiny Cat Guide to AI #2: Generative AI – What's Inside the Magic Box?

Wassim Soltani — Wed, 21 May 2025 19:23:01 +0000

Welcome back to The Tiny Cat Guide to AI!

In our previous post on Prompt Engineering, we explored how to give clear instructions to our creative AI felines. 😹

Now, let's dive deeper and peek inside the "engine room". What exactly is Generative AI? How does it power these amazing capabilities? What makes these models tick?

Generative AI is essentially a system combining countless learned patterns to create something entirely new.

To help visualize the fundamental concept of how it works, I’ve put together another visual story. This time, it involves a rather surprising (and overflowing) box of tiny cats!

^{Liked this carousel? Check out how to make one here!}

As our cat-filled box illustrates, you can think of Generative AI as that brand new, super-talented cat that emerges. It can meow happily, purr with contentment, and knows all the best sunbeam spots because it has, in a way, learned from the combined knowledge and experiences of all the other tiny cats it was trained on.

But beyond this high-level concept, working hands-on with these models reveals crucial mechanics that we, as developers and enthusiasts, need to grasp.

My experience building features focused specifically on content generation, such as:

My AI note-processing tool, Quickplan - generating summaries, action plans, and expanded points from raw text.
qmims, my AI-powered CLI tool using Amazon Q to generate and refine project READMEs and documentation files.
AI enhancements for my E-commerce platform - generating creative product descriptions and related marketing copy.

...has really highlighted several key technical aspects essential for understanding and effectively working with Generative AI:

💡 Context Window & Tokens:

Think of this as the AI's short-term, working memory. It can only "see" and process a limited amount of text (or data) at any given moment.

This limit is measured in "tokens" – which are roughly words or parts of words. Providing concise, highly relevant information within this window is critical for the AI to generate coherent and contextually appropriate output.

If crucial information falls outside this window, the AI effectively forgets it for that specific interaction.

🌡️ Temperature:

This setting is your control knob for randomness in the AI's output.

A low temperature (e.g., 0.1-0.3) makes the AI more predictable, focused, and deterministic – great for tasks requiring factual accuracy, like summaries or straightforward Q&A.

A high temperature (e.g., 0.7-1.0+) encourages more creative, diverse, and sometimes unexpected results, which can be useful for brainstorming, varied content generation, or artistic applications.

Finding the sweet spot for your specific use case is key.

⚙️ Function Calling & Tools:

Modern Large Language Models (LLMs) aren't just isolated brains; they can be empowered with "tools".

This is often enabled via a mechanism called "function calling". It allows the LLM to pause its generation, call an external API or a predefined function in your code (to fetch real-time data, query a database, perform calculations, interact with other services), and then use the result from that tool to inform and complete its final response.

This dramatically expands their capabilities beyond text generation.

🌍 Grounding (e.g., RAG):

A well-known challenge with AI is its tendency to "hallucinate" – invent plausible-sounding but false or irrelevant information.

Techniques like Retrieval-Augmented Generation (RAG) are vital for combatting this. RAG involves 'grounding' the AI by providing it with specific, up-to-date, and factual documents relevant to the user's prompt before it generates a response.

The AI is then instructed to base its answer primarily on this provided context, which dramatically improves factual accuracy and relevance.

Understanding these mechanics is essential for moving beyond basic prompting. It allows us to more reliably harness the true power of Generative AI for building sophisticated and useful applications.

What's one technical aspect of LLMs you've found particularly crucial or challenging to work with in your own projects? Let's share some insights in the comments below! 👇

Wanna go to the library with me?

Wassim Soltani

May 22 '25

The Tiny Cat Guide to AI #3: RAG – Tiny Librarians

#ai #rag #machinelearning #learning

Comments

4 min read

The Tiny Cat Guide to AI #1: Prompt Engineering – Directing the AI Ballet

Wassim Soltani — Tue, 20 May 2025 15:47:49 +0000

Ever feel like getting an AI to do exactly what you want is like trying to organize a ballet for super creative, slightly chaotic tiny cats? Yeah, me too! 😹

To break down how we can better direct these chaotic tiny cats, I've visualized the core ideas of Prompt Engineering using some feline friends. You can see this little story in action in the carousel embedded right below!

^{Liked this carousel? Check out how to make one here!}

It turns out, just vaguely telling an AI (or a cat) to "do something cool" doesn't quite cut it. But give it clear, detailed instructions? That's when the magic happens! ✨

Prompt engineering has become absolutely essential in my day-to-day work. Building AI features has definitely thrown some curveballs my way, whether I'm working on:

An AI feedback system for educational content
A browser extension using OCR/AI for data extraction
My own AI note-processing tool, Quickplan
AI enhancements (like semantic search & content generation) for my E-commerce platform

Some of the common challenges I've wrestled with (and where good prompting is key) include:

🤯 Getting AI to output reliably structured data (like specific JSON or Markdown formats for Quickplan) instead of just... a wall of text.

🧠 Ensuring AI truly understands the context – like applying specific pedagogical guidelines for educational feedback versus generating creative product descriptions.

⚖️ Balancing helpful AI creativity with the need for factual accuracy, especially when extracting data or generating e-commerce content.

🖼️ The dreaded "text hallucinations" when requesting diagrams or images! Asking for a simple chart and getting... an artistic interpretation of letters. 😖

🎭 Maintaining a consistent tone and style for the AI's output across multiple interactions or for different branding needs.

So, how do we give our AI cats better stage directions for their ballet? Here’s what has consistently helped me craft more effective prompts:

✅ Be Hyper-Specific: Don't just ask for "a summary." Define the desired length, target audience, tone (e.g., formal, casual, witty), and explicitly list any key points that must be included or excluded. Details transform vague requests into actionable instructions.

✅ Provide Rich Context: Tell the AI the 'why' and the 'who'. What's the ultimate goal of the meeting notes for Quickplan? Who is the end-user of the feedback? Providing this background helps the AI make better inferences and tailor its response more appropriately.

✅ Set Clear Boundaries & Constraints: Explicitly state what the AI should not do. For example: "Avoid technical jargon," "Focus only on the financial aspects discussed," or "Generate NO text elements inside the requested image."

✅ Define the Output Format Explicitly: If you need structured data, ask for it directly. Specify JSON with a particular schema, Markdown with headers, a numbered list, step-by-step instructions, or even a table format. The clearer your definition, the higher the chance of getting a usable output.

✅ Iterate, Iterate, Iterate: Your first prompt is rarely your masterpiece. Treat prompting as an iterative process. Test your prompt, analyze the output, identify where the AI stumbles or misunderstands, then tweak your instructions and repeat.

✅ Know Your Model: Different AI models (e.g., GPT-4, Claude, Llama) have distinct strengths, weaknesses, knowledge cut-offs, and stylistic quirks. Understanding the specific model you're working with can help you tailor your prompts for optimal performance.

Prompt engineering really is about clear communication – it's how we effectively guide these incredibly powerful (and creative!) AI brains. Hopefully, the cat ballet in the carousel helps illustrate these points!

What are your go-to prompt engineering tricks, biggest headaches, or favorite cat-herding analogies for AI? Share your thoughts and experiences, I'd love to hear them! 👇

What's that? A box full of tiny cats?!

Wassim Soltani

May 21 '25

The Tiny Cat Guide to AI #2: Generative AI – What's Inside the Magic Box?

#ai #llm #machinelearning #learning

Comments

3 min read

^{Created by Wassim Soltani}

No More Static Posts! I Built an Accessible, High-Performance Carousel for DEV.to

Wassim Soltani — Mon, 19 May 2025 23:30:01 +0000

Hey everyone! 👋

Like many of you, I love using visual storytelling in my technical content. On LinkedIn, I've been using image carousels to break down complex topics. They're engaging and make information so much more digestible!

But when I wanted to bring that same energy to my DEV.to posts, I hit a snag: native carousel support isn't really a thing here. Since DEV does support CodePen embeds, I decided to take matters into my own hands and build my own solution: a Dynamic Image Carousel!

I'm thrilled to share it with everyone. The best part? It's designed to be easily adapted for your own use! You can simply fork my Pen, change the image source, and you're good to go (with a few considerations, of course).

How to Use This Carousel in Your DEV.to Posts

Ready to add some visual flair to your articles? Here’s how to get started:

Prepare Your Images:
- Create your series of images. For best results and a good square aspect ratio, I recommend a size of 900x900 pixels per image.
- Name them sequentially: 1.png (or .jpg, .jpeg, .webp), 2.png, 3.png, and so on.
Host Your Images:
- Upload your images to an image hosting service that provides direct URLs (ImageKit, AWS S3, even GitHub Pages if serving raw files, etc).
- You'll need a common base URL for the folder where these sequentially named images are stored.
Fork & Configure on Codepen:
- Go to my DEV Carousel Codepen and click the "Fork" button (usually in the bottom right of the editor view) to create your own copy.
- In the JavaScript panel of your forked Pen, find and update the IMAGE_BASE_URL constant with the URL of your image folder:
```
  const IMAGE_BASE_URL =
    "https://your-hosting-service.com/your-image-folder/";
```
Test Your Fork:
- Make sure your carousel loads your images correctly within your forked Codepen. Save your Pen.
Embed in DEV.to:
- Once your forked Codepen is saved and working with your images, copy the URL of your Pen.
- In your DEV.to markdown editor, use the Codepen Liquid tag like this, replacing the example URL with the URL of your forked Pen:
{% codepen https://codepen.io/YOUR_USERNAME/pen/YOUR_PEN_SLUG_HASH %}

And voila! ✨

So, What's Under the Hood? (The Techy Bits)

For those interested in the mechanics, I focused on building this with vanilla JavaScript, HTML, and CSS, emphasizing:

Dynamic Image Loading: It doesn't need a predefined list of image URLs. It discovers images by trying sequential numbers (1.png, 2.png, etc.) with various formats from your IMAGE_BASE_URL.
Performance Optimizations:
- Parallel Image Discovery: Uses Promise.all (with a Promise.race for timeout) to check for the existence of multiple potential images and their formats simultaneously, making the initial discovery faster.
- Image Existence Caching: Once an image's existence (or non-existence) at a specific URL is confirmed, this status is cached in a Map to avoid redundant new Image() checks for the same URL during the discovery phase.
- Intelligent Preloading: When you navigate, it attempts to preload the next and previous slides' images to make transitions feel smoother.
- Uses CSS will-change for transform animations.
Accessibility (WCAG 2.1 AA in mind):
- Full keyboard navigation.
- ARIA roles and attributes (aria-roledescription, aria-label, aria-selected, sr-only live region for slide changes).
- Visible focus indicators and High Contrast Mode considerations in CSS.
Responsive & Interactive:
- Adapts to different screen sizes (CSS aspect-ratio with fallbacks).
- Touch swipe and mouse drag support for navigation.
Error Handling & Fallbacks:
- Gracefully handles images that fail to load by showing a fallback SVG.
- Includes a loading indicator during initial image discovery.
- Provides a <noscript> message.

You can dive into the HTML, CSS, and JavaScript directly in the Codepen to see all the details!

What's Next?

I built this carousel because I wanted a better way to share visual stories here on DEV.to, and I hope it can be useful to some of you too!

If you found this interesting or use the carousel, I'd love to hear about it in the comments. Also, consider dropping a ❤️ on CodePen!

Be sure to follow me here on DEV.to! I'm planning to share more of my projects and insights on AI, web development, and building cool tools. Stay tuned for some interesting posts!

Happy coding! 👨‍💻

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

Wassim Soltani — Sat, 10 May 2025 17:32:31 +0000

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:

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.
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.
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., ) 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.
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.