How to Describe a Bug Clearly in English

The single most useful skill in any bug report is describing the problem so clearly that another engineer can reproduce it without asking a single question. Most bug reports fail at this. This guide gives you a simple structure and the precise English that turns “it doesn’t work” into a report someone can fix today.

---

The Golden Rule: Expected vs Actual

Every clear bug description contrasts two things:

• What you expected to happen.
• What actually happened instead.

“I expected the form to submit and show a success message. Instead, the page reloaded and the form was empty, with no error shown.”

If you only describe one side, the reader has to guess the other. Always state both.

---

A Simple Structure

1. Summary — one sentence.
2. Steps to reproduce — numbered.
3. Expected result.
4. Actual result.
5. Environment — browser, OS, version, account type.
6. Evidence — screenshot, log, error message.

Summary: Uploading a PDF over 5MB fails silently. Steps: 1. Go to Documents. 2. Click Upload. 3. Select a 6MB PDF. Expected: The file uploads and appears in the list. Actual: The progress bar reaches 100%, then nothing happens. No file appears, no error shown. Environment: Chrome 124, macOS, Pro account.

---

Precise Verbs for Describing Behaviour

Vague verbs slow everyone down. Use precise ones:

Vague	Precise
“It breaks.”	“It throws a 500 error.”
“It’s weird.”	“The list shows duplicate entries.”
“It freezes.”	“The UI becomes unresponsive for about ten seconds.”
“Nothing happens.”	“The button click has no visible effect and logs no request.”

“The request hangs for thirty seconds, then times out with a 504.”

---

Describing Frequency and Conditions

Reproducibility is gold. Tell the reader how often and under what conditions:

• “This happens every time.”
• “It’s intermittent — roughly one in five attempts.”
• “It only happens when the user has more than 100 items.”
• “I can’t reproduce it consistently, but it tends to occur after the session has been open for a while.”

“It only fails on mobile Safari; desktop browsers work fine.”

The word “only” is powerful — it narrows the search dramatically.

---

Including the Error Message Verbatim

Never paraphrase an error. Copy it exactly.

“The console shows: TypeError: Cannot read properties of undefined (reading 'id') at cart.js:42.”

Paraphrasing (“some error about undefined”) loses the detail that often points straight to the cause.

---

Words That Add Useful Context

• “This started happening after the last deploy.”
• “It used to work in the previous version.”
• “This is a regression — it worked last week.”
• “It’s a blocker — I can’t continue testing until it’s fixed.”

“This is a regression from version 2.3 — the same flow worked there.”

The word “regression” tells the team that something that worked is now broken, which changes how urgently they treat it.

---

What to Leave Out

A clear report avoids:

• Guesses about the cause stated as fact (“it’s definitely the database”). Offer them as theories: “my guess is it’s related to caching, but I’m not sure.”
• Emotional language (“this is a disaster”). State impact instead: “this blocks all new sign-ups.”
• Three bugs in one report — file them separately.

---

A Phrase Bank for Bug Reports

“Steps to reproduce:” “Expected behaviour:” “Actual behaviour:” “This happens consistently / intermittently.” “It only occurs when…” “This is a regression from…” “Attaching a screenshot and the full stack trace below.”

---

Quick Before-and-After

Before: “Upload is broken, please fix.”

After: “Uploading PDFs over 5MB fails silently on Chrome (steps below). Expected: file uploads. Actual: progress hits 100% then nothing happens, no error. Consistent. Screenshot and console log attached.”

The second version can be fixed today; the first generates a day of questions.

---

Describing a bug clearly is a gift to whoever fixes it — and often that’s your future self. Contrast expected with actual, number your steps, quote errors verbatim, and state the conditions precisely. Master this simple structure and your bug reports will become the ones developers actually want to pick up.

Navigating Nuances: Speaking Your Bug Clearly – For Non-Native Developers

Let’s face it; technical jargon isn’t always universally understood. Even within a team, subtle differences in phrasing can significantly impact how clearly a bug is communicated and, consequently, the speed at which it gets resolved. As a non-native English speaker, focusing on precision and clarity – particularly when describing issues – is crucial for demonstrating professionalism and facilitating effective collaboration. It’s not just about stating what went wrong; it’s about how you describe it in a way that allows others to quickly understand, reproduce, and ultimately fix the problem. This isn’t simply about using correct grammar, but understanding the specific nuances of professional technical communication.

One common pitfall is relying solely on translating technical terms directly. For example, instead of saying “the API returned an error,” which might be perfectly understandable within a team familiar with that terminology, consider phrasing it as: “The API call failed to return data, resulting in a 500 Internal Server Error.” This provides immediate context – what failed and why. Similarly, when detailing reproduction steps, avoid vague instructions like “try running the code.” Instead, use precise verbs and details. “Please run npm start and navigate to /users/123 in your browser; you should then observe…” is far more actionable.

A crucial shift involves moving beyond simply stating “it’s broken” – a phrase that offers no immediate guidance. Aim for descriptions centered on observable behavior. Instead of “the button doesn’t work,” try, “When clicking the ‘Submit’ button, no action occurs and there is no visual feedback to indicate success or failure.” This focuses on what the user sees and experiences, which is often more relatable and easier to diagnose. Remember, a good bug report isn’t about your frustration; it’s about providing actionable information for someone else to solve the problem efficiently.

Finally, remember that clear communication extends beyond written reports. Slack messages describing bugs should follow similar principles – concise, specific, and focused on observable issues. Avoid ambiguity. Instead of “something’s wrong with the login,” try “I’m unable to log in; after entering my credentials, I receive a ‘Invalid username or password’ error.” Using precise language builds trust and demonstrates your commitment to clear problem-solving.