'How do I write a good User Story?' is a question I hear a lot. That is the wrong question.
The problem with this question is the fundamental misunderstanding of the entire purpose & technique of User Stories. I accept that User Stories do require information to be written in the form of both description and acceptance criteria, and that it would of course be helpful if they were ‘written’ well, but they really are a token for conversation, the starting point and communication tool to clarify and confirm what Users want, why they want it and to confirm what “good” would look like.
Communication
The primary purpose of the User Story is to improve communication between the Development Team and the end User of the product. By their very nature, User Stories force people to be concise concerning the amount of detail they provide in the ‘story’, meaning the team should hold a structured conversation in order to populate the detail and fill out a common and shared understanding across the entire team.
Where does the detail go?
Scrum or Agile doesn't say ‘no’ to documentation. This is a common misinterpretation of the Agile Manifesto’s 'Working software over comprehensive documentation’. Once teams have discussed the User Story and gained the necessary detail that is required for delivery, this information can be documented in any way you want. Before JIRA, Version One, Agile Central etc. Teams would simply paperclip their documentation pack to the back of the User Story card. Of course, now, a double-click on JIRA and the job is done. The point I'm making is if you want detail and documentation, have it, not more than you need or just in case, but don't try and cram the detail into a User Story Structure.
When should we add the detail - just in in time?
The concise information that is provided as a part of a User Story structure requires the team to communicate and then capture this information in the form of documentation. The other advantage of the User Story is that it acts as a ‘placeholder’ or ‘promise’ for a future conversation between the team and the Product Owner/Manager and User. It is crucial to ensure that we only add the detail to the User Story when it becomes valuable and is being considered for development. The detail is added through a process of Backlog refinement driven by the team's conversation. Many effective teams work with a 6-week planning horizon, whereby they incrementally add detail, to the User Story over a period of 6 weeks prior to delivery. A 6-week planning horizon isn't the law, shorter, of course, would be better for reducing potential waste as long as risk remains low.
So what is a better question? ‘How do I discuss user actions and needs more effectively with a reliable and regular structure that enables my team to get the right information in order to discuss our execution more effectively so that we deliver the right thing the first time?’.