How to Write Great Issue Descriptions for Your Public Board

A public board is only as good as the issues on it. Vague titles and technical descriptions confuse users and reduce engagement. Well-written issues attract votes, reduce duplicates, and make your board feel professional.

Titles: Clear, Specific, Searchable

The title is what users see first. Write it for your users, not your engineering team.

Good titles:

• "Add CSV export for reports"
• "Dark mode for the dashboard"
• "Support login with Google SSO"
• "Fix: images not loading on Safari"

Bad titles:

• "Export improvement" — Too vague. Export what? How?
• "Auth enhancement" — Users don't think in auth layers
• "Perf issue #4821" — Internal jargon, not discoverable
• "Bug" — Meaningless without context

Use the words your users would search for. If they call it "download," don't title it "export."

Descriptions: User Perspective, Not Implementation

Write descriptions as if explaining to a customer, not filing an internal ticket:

Good:

"Currently there's no way to download report data. This feature would add a CSV export button to the reports page so you can analyze data in a spreadsheet."

Bad:

"Implement export endpoint on /api/reports with CSV serialization. Update ReportController and add streaming response handler."

The second description is useful for your team — put it in a Linear comment. The public-facing description should explain what and why, not how.

Structure for Clarity

For longer descriptions, use a simple structure:

• What: What the feature does or what the bug affects
• Why: Why it matters to users
• Current workaround: If one exists (for bugs)

Skip internal priority labels, sprint assignments, and technical architecture notes.

Status-Appropriate Language

Match your descriptions to the issue status:

• Backlog: "We're tracking interest in this feature"
• Planned: "We've committed to building this"
• In Progress: "Development is underway"
• Done: "This feature is now available"

Maintaining Quality Over Time

As your board grows, quality can drift. Review issues periodically:

• Rewrite vague titles that aren't getting votes
• Clean up internal jargon that leaked into descriptions
• Merge duplicate issues with different wording
• Archive old issues that are no longer relevant

A curated board with well-written issues builds trust and drives higher engagement.