Writing feature requests when you don't have technical chops is hard.

Communicating your business needs is no simple skill. I've seen so many tickets and tasks go horribly wrong. And people on both sides of the fence frustrated by faulty communication.

Writing clear feature requests and bugs is a vital, unsung skill.

But with these five simple tips, you can ensure you're never misunderstood.

Tip #1: Explain how to reproduce the problem

Don’t say: "It doesn't work!”. Do say: "When I click here, under these conditions, this behaviour occurs". 

Why? Reproducing the bug helps developers understand what has gone wrong. And test that it is fixed. Otherwise, the ticket gets closed with a "cannot reproduce" comment.

Tip #2: Keep to one issue per ticket

Don’t say: “Oh and by the way…”  Do create other tickets for other related subjects. These can be sub tasks of an overarching meta task.

Why? A task can’t be assigned to two people at the time and different subjects require different skills.

Tip #3: Provide a clear victory condition

Don’t say: “We should improve this.” Do say: “Users need to be able to do this action under these conditions, because they have this need.”

If we don’t understand the problem we can’t solve it!

Tip #4: Don't presume the technical solution

Don’t say: “We need this technical feature”. Do say: “We have this need.”

Why? There can be simpler path to the same outcome. If we understand the need we can propose alternate solutions.

Tip #5 Don't use technical language

Don’t use technical terms or propose technical solutions unless you really know what you’re saying. Eg. “the database needs better indexing”. Do say what the end results is, e.g. “This page is loading too slowly”

Why? You may be pointing developers in the wrong direction.

Bad communication is not a fatality. And when things get done, everyone is happy. Especially developers.