English for Software Developers: How to Explain a Bug Clearly

Why “broken” creates more work

Words such as broken, wrong, weird, randomly, and there is an issue communicate frustration. They do not communicate behavior. Your teammate cannot execute the word “broken.” It has no trigger, result, environment, or stack trace.

A good bug explanation names what the system did. Mozilla’s bug-writing guidelines recommend a specific summary and precise reproduction steps. Google’s technical-writing guidance similarly recommends specific verbs and clear subjects instead of vague constructions.

The technical scenarios in this guide are teaching examples, not reports of named real incidents.

The 60-second “broken” rewrite

Take one sentence from a recent ticket that contains “broken,” “issue,” “wrong,” “randomly,” or “doesn’t work.” Rewrite it with this minimum structure:

When [condition], [specific actor or component] [specific verb plus actual result] instead of [expected result].

If your sentence contains several actions, split it. Your teammate should not need to compile your paragraph.

Build the core sentence: trigger, actual behavior, expected behavior

The first useful sentence of a bug report usually answers three questions:

1. What triggers the problem?
2. What actually happens?
3. What should happen instead?

This structure works because it shows the gap between the current behavior and the intended behavior. Official GitHub issue-form examples separate current behavior, expected behavior, reproduction steps, and environment for the same reason: each field answers a different question.

Use verbs that show the failure

Clear bug English depends more on strong verbs than advanced vocabulary. Useful verbs include:

• returns: “The endpoint returns 401 after token refresh.”
• redirects: “The form redirects to the login page instead of the confirmation page.”
• duplicates: “The import job duplicates the final row.”
• omits: “The export omits records created after midnight UTC.”
• truncates: “The modal truncates filenames longer than 40 characters.”
• freezes: “The editor freezes after pasting a table with more than 100 rows.”
• times out: “The request times out after the second retry.”
• rejects: “The validator rejects a valid IPv6 address.”

Three examples across the stack

UI bug: “After a user removes the final item from the cart, the checkout button remains enabled. It should become disabled because the cart is empty.”

API bug: “When the client retries POST /orders with the same idempotency key, the API creates a second order instead of returning the original response.”

Data bug: “After an administrator changes a user’s timezone, the activity report continues grouping events by the old timezone until the next day. The report should use the updated timezone immediately.”

Write a title that identifies the bug

A useful title is not a category such as “Payment bug.” It is a compressed explanation.

• Weak: “Problem with checkout”
• Better: “Checkout creates duplicate orders after a timed-out payment retry”
• Weak: “Mobile crash”
• Better: “Android app crashes when the screen rotates during image upload”

The title identifies the failure. The reproduction steps prove that another person can reach it.

Write reproduction steps another person can run

Reproduction steps are not a story about what you remember doing. They are ordered instructions. Mozilla calls precise steps one of the most important parts of a useful report, and GitLab’s official bug-report template separates steps, current behavior, expected behavior, logs, screenshots, and possible fixes.

Start with preconditions. Then use numbered steps with one action per line. Finish with the observed result.

Weak version

“I was uploading a profile image on Android and rotated the phone, and then it crashed after I selected the photo, but it does not happen every time.”

Executable version

Preconditions: Android 15, app version 4.8.1, user is signed in, photo permission is enabled.

1. Open Profile.
2. Select Change photo.
3. Choose an image larger than 8 MB.
4. While the upload progress indicator is visible, rotate the device from portrait to landscape.
5. Observe the app.

Actual result: The app closes and Android displays the crash dialog.

Expected result: The upload should continue, or the app should preserve the upload state after rotation.

Frequency: Reproduced in 4 of 5 attempts.

Notice what the clearer version does not include: a long theory about lifecycle handling, fragments of unrelated debugging, or every tap made before the test. It preserves the path that matters.

Add environment and evidence without dumping everything

Environment details define the boundary of the bug. They can include the browser, operating system, app or build version, device, account state, feature flag, locale, network condition, or test data. Include a detail when it can change reproduction, narrow diagnosis, or explain impact.

Chromium’s bug-reporting guidelines recommend a high-level description, detailed steps, expected behavior, relevant browser comparisons, screenshots when useful, and a simplified test when possible.

Use evidence as a pointer, not a landfill

A good evidence sentence tells the reader why the attachment matters:

• “The attached network trace shows that the refresh request succeeds, but the next API call still uses the expired token.”
• “Request ID 8f31c2 corresponds to the failed checkout attempt at 14:22 UTC.”
• “The screenshot shows the button enabled after the cart count reaches zero.”

Environment explains where the bug lives. Frequency explains how reliably it appears.

Explain intermittent bugs and uncertainty professionally

An intermittent bug is a bug that does not happen every time. These defects are difficult enough without describing them as supernatural. Replace “randomly” with the best boundary you can honestly provide.

Better frequency language

• “I reproduced it in 3 of 10 attempts.”
• “It occurs only after the laptop resumes from sleep.”
• “It has happened twice in production, but I have not reproduced it locally.”
• “It appears more often on slow connections; I have not confirmed whether network latency is the cause.”
• “I cannot reproduce it consistently, but both failures occurred after the token had been refreshed.”

Separate observation from hypothesis

Your credibility increases when your level of certainty matches your evidence.

Avoid jumping from “I saw stale data” to “Redis caused the bug.” Start with the symptom. Add the theory in a separate sentence:

“The profile page displays the previous name for about five minutes after an update. I suspect cached data because a direct database read returns the new value immediately, but I have not confirmed which cache layer is responsible.”

Saying “I have not confirmed the cause” does not make you sound weak. It tells the team where the known facts end.

Describe impact before arguing about severity or priority

Teams define severity and priority differently. A report becomes more useful when it describes the impact first and lets the team apply its own labels.

Useful impact questions

• Who is affected?
• What task is blocked or degraded?
• Is data lost, duplicated, exposed, or only displayed incorrectly?
• Does the failure affect every attempt or a narrow condition?
• Is there a safe workaround?

Impact sentence patterns

• “This blocks new users from completing account verification.”
• “Existing users can still sign in with a password, but Google sign-in fails.”
• “The issue affects the visual layout only; the form still submits successfully.”
• “The duplicate request can create two paid orders, so retrying is not a safe workaround.”
• “Administrators can avoid the problem by refreshing the report after changing the timezone.”

“Critical” is an argument. “Customers can be charged twice, and there is no safe workaround” is evidence.

A complete report still has to survive compression. In chat or stand-up, keep the same evidence path and shorten only the format.

Adapt the same bug for a ticket, chat, and stand-up

Here is the same authentication bug at three levels of detail.

Full ticket

Title: Google sign-in returns new Safari users to the login page

Environment:
- Safari 18.4
- Production
- New account with no existing session

Actual behavior:
Selecting “Sign in with Google” completes the Google flow, then returns the user to the login page without creating a session.

Expected behavior:
The application should create the session and open the dashboard.

Steps to reproduce:
1. Open the login page in Safari 18.4.
2. Select “Sign in with Google.”
3. Authenticate with a Google account that has not used the app before.
4. Observe the redirect after authentication.

Frequency:
3 of 5 attempts.

Impact:
New Safari users cannot complete registration through Google sign-in. Password registration still works.

Evidence:
HAR file and request IDs are attached. The callback returns 302, but the following dashboard request has no session cookie.

Hypothesis:
I suspect the session cookie is not persisted after the OAuth callback, but I have not confirmed the cause.

Team chat message

Google sign-in is failing for new users on Safari 18.4. The Google flow completes, but the app returns to the login page without a session instead of opening the dashboard. I reproduced it in 3 of 5 attempts. Password registration still works. I added request IDs and a HAR file to the ticket.

Thirty-second stand-up explanation

“I found a Safari-specific issue in Google sign-in. New users complete authentication, but the app redirects them to the login page without creating a session. I reproduced it three times in five attempts. Password registration is a workaround. I suspect the callback cookie is not being persisted, and I am checking that next.”

Read the spoken version aloud. Remove any sentence that does not explain the trigger, behavior, impact, evidence, or next step. A live explanation is the compressed version of the same executable path, not a separate skill.

Interactive practice: The Bug Explanation Debugger

For each scenario, choose the clearest description before opening the answer. Do not choose the longest option automatically. Choose the one that transfers the most useful evidence without pretending to know more than the reporter knows.

Run your own report through this checklist

Every unchecked item points to an exact repair. Add a condition, choose a stronger verb, split the steps, label the theory, or describe the impact. This is not a grammar score. It is a handoff test.

Copyable templates and a five-minute practice routine

Bug ticket template

Title: [Component] [actual behavior] when [trigger or condition]

Environment:
- Version/build:
- Browser/OS/device:
- Account state, feature flag, locale, or network condition if relevant:

Actual behavior:
[What the system does]

Expected behavior:
[What the system should do]

Steps to reproduce:
1.
2.
3.

Frequency:
[Every time / X of Y attempts / intermittent under these conditions]

Impact:
[Who or what is blocked, degraded, duplicated, lost, exposed, or delayed]

Evidence:
[Relevant log excerpt, screenshot, request ID, trace, or reduced test]

Workaround:
[Safe workaround, or “No safe workaround found”]

Hypothesis:
[Optional. Use “I suspect…” and explain why. Do not present it as confirmed.]

Team chat template

[Component] fails when [trigger/environment].
Actual: [visible behavior].
Expected: [intended behavior].
Frequency: [tested frequency or condition].
Impact: [who or what is affected].
Evidence/ticket: [link or identifier].
Hypothesis/next step: [clearly labeled theory or investigation].

Thirty-second spoken template

“I found an issue in [component]. When [trigger and environment], it [actual behavior] instead of [expected behavior]. I reproduced it [frequency]. It affects [impact]. I have [evidence], and my next step is [investigation or fix].”

Five-minute practice

1. Choose one real bug you recently reported.
2. Rewrite its first sentence with trigger, actual behavior, and expected behavior.
3. Replace every vague verb with a specific system action.
4. Separate observations from hypotheses.
5. Say the 30-second version aloud twice: once while reading, then once without reading.

The goal is not to memorize one perfect paragraph. It is to make the information order automatic when someone asks, “What exactly is happening?”

Use words that survive the handoff

“Login is broken sometimes” can hide a sharp technical observation inside a foggy sentence. The repair is not more impressive vocabulary. It is a clearer path: condition, actual behavior, expected behavior, reproduction, environment, frequency, evidence, impact, and honest uncertainty.

Before submitting your next report, ask one question:

Could a teammate run these words and reach the same failure?

If the answer is no, do not make the report longer by default. Make it more executable. Add the missing coordinate. Choose the stronger verb. Move the theory below the facts. State the impact without drama.

You do not need perfect English. You need words that survive the handoff.