Should Design instructions be part of Jira story descriptions?

Question

I am a business analyst and i write user stories for my projects regularly. I have got suggestions from people that the design instructions shouldn't be part of Jira story description.

When i say design instruction, which means where to show what? For eg. Where should be the label shown on the particular field? In the field, above the field or beside the field? I usually mention this in my stories, so it gives better clarity to my Devs and QAs.

but i want to know whether i doing it right, or not?

Petter Gonçalves · Answer

Hello Abhishek,

Thank you for your answer.

I perfectly understand the way you are describing your stories and I particularly agree with it.

My only suggestion is that you could add topics to your description, describing the steps you want to change and the reason (if it's necessary) for the implementation.

You can also check the feature requests on https://jira.atlassian.com to check how Atlassian handle with their design and improvement implementation, using any template that you think that would be useful to better organize your stories.

Abhishek Sharma_sp5vah · Answer

Hello Petterson,

Thank you for answering. I agree that there is no right or wrong way to add data in the JIRA stories.

I have always been organizing my stories in such a way that i add every major and minor information in the description. For e.g. If there is a delete functionality then "on click delete button a confirmation pop-up should appear." This is how i am told to write the story.

This is how i write the story for same functionality. "On click delete button, a pop-up should appear with the following message "Are you sure, you want to delete this record?" with a button to select Yes or No. On click Yes, the record should be deleted from the database. On click No, the pop-up will be disappeared and the record won't be deleted"

This description includes what should be there on the pop-up which buttons should be there, and what should happen on those buttons.

Hope this helps in understanding my confusion.

Petter Gonçalves · Answer

Hello Abhishek,

There is no right or wrong way to fill data on your JIRA Stories, It will depend on how you use your JIRA and how you would like to organize it.

That being said, can you please let us know what are the people meaning when they say that the design instructions shouldn't be part of Jira story description? Is this being confusing on their perspective?

If the problem is that there are other kinds of information on the Story description and you think that the design instructions would be better displayed if this information was in another field, you can create a new custom field to add this kind of information.

Please, check the instructions below for more details:

- Adding a new Custom Field