A good bug report is like a good story—it has a beginning, middle, and end. After reviewing thousands of bug reports, I've learned what makes developers actually want to fix your bugs. Here's how to write reports that get results.
The Anatomy of a Great Bug Report
1. A Clear, Descriptive Title
Bad: "Button doesn't work"
Good: "Submit button on checkout page doesn't respond when clicked on mobile Safari"
The title should tell the developer:
- What isn't working
- Where it's not working
- When it doesn't work (if relevant)
2. Steps to Reproduce
This is the heart of your bug report. Make it foolproof.
Template:
1. Go to [specific URL]
2. Click on [specific element]
3. Enter [specific data] in [specific field]
4. Click [specific button]
5. Observe the error
Pro tip: Test your own steps. Can you reproduce the bug following only what you wrote? If not, revise.
3. Expected vs. Actual Behavior
Be explicit about what should happen and what actually happens.
Example:
Expected: User is redirected to the dashboard after successful login
Actual: Page shows a loading spinner indefinitely
4. Environment Details
Context matters. Include:
Browser: Chrome 118.0.5993.88
OS: macOS Sonoma 14.1
Screen resolution: 1920x1080
User role: Standard user
Account type: Free tier
For mobile:
Device: iPhone 14 Pro
OS: iOS 17.0.3
App version: 2.5.1
Network: WiFi
5. Visual Evidence
A screenshot is worth a thousand words. A video is worth a million.
Tools I use:
- Loom - Quick screen recordings with annotation
- CloudApp - Fast screenshots with markup
- Chrome DevTools - Network tab screenshots for API issues
Pro tip: For intermittent bugs, record a video. It captures context that screenshots miss.
6. Additional Context
- Frequency: Does this happen every time or intermittently?
- Impact: How many users are affected?
- Workaround: Is there a way to avoid the issue?
- Related issues: Link to similar bugs
Real Example: Before & After
Before (Bad Report)
Title: Login broken
Description:
Can't login. Fix it please!
After (Good Report)
Title: Login fails with "Invalid session" error for SSO users on first attempt
Description:
Users authenticating via Google SSO receive an "Invalid session" error on their
first login attempt. The second attempt succeeds.
Steps to Reproduce:
1. Clear browser cookies
2. Navigate to https://app.example.com/login
3. Click "Sign in with Google"
4. Select Google account and authorize
5. Observe "Invalid session" error page
Expected: User is logged in and redirected to dashboard
Actual: Error page appears with message "Invalid session. Please try again."
Environment:
- Browser: Chrome 118.0.5993.88
- OS: Windows 11
- User account: Standard user with Google SSO enabled
- Reproduced: 5 out of 5 attempts
Additional Context:
- Only affects SSO users (email/password login works fine)
- Only occurs on first login after clearing cookies
- Second login attempt always succeeds
- Console shows: "token_expired" error before redirect
Workaround: Click "Sign in with Google" again
Screenshots:
[Attached: error-page.png, console-logs.png]
Video: https://loom.com/share/[video-id]
See the difference?
Common Mistakes to Avoid
❌ Vague Descriptions
"It's not working" tells developers nothing.
❌ Missing Steps
"Just try to login" - but with what credentials? Which login method? From which page?
❌ Combining Multiple Issues
One bug = one report. If you found 5 bugs, create 5 reports.
❌ Emotional Language
"This stupid button never works!"
Instead: "Submit button does not respond to clicks after form validation errors."
❌ Assumptions About the Cause
"The database is probably corrupted"
Just report what you observed. Let developers investigate the cause.
Bug Report Template
Here's a template I use:
## Summary
[One sentence description]
## Steps to Reproduce
1.
2.
3.
## Expected Behavior
[What should happen]
## Actual Behavior
[What actually happens]
## Environment
- Browser/Device:
- OS:
- Version:
- User type:
## Screenshots/Videos
[Attach here]
## Additional Information
- Frequency:
- Severity:
- Workaround:
- Related issues:
## Console Logs[Any relevant console errors]
Making Bug Reports Even Better
For Critical Bugs
- Flag as "Critical" or "Blocker"
- Notify the team immediately (don't just log it)
- Include impact estimation (e.g., "Blocks checkout for all users")
For Intermittent Bugs
- Document the pattern (time of day, specific conditions)
- Include frequency data (e.g., "Occurs ~30% of the time")
- Attach multiple examples
For UI/UX Issues
- Include design specs if available
- Note accessibility concerns
- Test across different screen sizes
The Developer Perspective
I asked several developers what makes a bug report great. Here's what they said:
"Clear reproduction steps. If I can't reproduce it, I can't fix it." - Backend Developer
"Screenshots with the issue highlighted. Don't make me search for what's wrong." - Frontend Developer
"Console logs. They often show the real problem before I even start debugging." - Full Stack Developer
Tools That Help
- Jira - Industry standard, powerful but complex
- Linear - Modern, fast, great UX
- GitHub Issues - Perfect for open source
- Notion - Flexible for small teams
- BugHerd - Visual feedback directly on web pages
Key Takeaways
- Be specific - Exact URLs, exact steps, exact errors
- Be reproducible - Test your own steps
- Be visual - Screenshots and videos
- Be contextual - Environment matters
- Be professional - Focus on facts, not frustration
Remember: A good bug report is a gift to developers. It helps them fix issues faster, which means a better product for everyone.
Got a bug report template you love? Share it in the comments!