Skip to main content

Where to write the specs of a user story?

Last post 07:26 pm July 21, 2021 by Jappe Kieckens
2 replies
02:43 am May 9, 2020

Hi there, 

Im new to agile and i just used Asana to write user stores. And i have these questions:

1- Where to the write the detailed specs for each user story. As i used to write a detailed SRS that specify each use case, scenario, constrains, exceptions, messages. Are these all to be written within the user story? or different artifacts should be created? 

2- where the technical design come within agile? like system design, and database schema? 

3- It is ok to keep all these in Asana or Jira? or i should export everything in single document? 


Thanks in advance. 


11:54 pm May 10, 2020

With design and associate design documentation, it's important to keep the value of

Working software over comprehensive documentation

which is supported by principles such as

Our highest priority is to satisfy the customer through early and continuous delivery of valuable software.


Business people and developers must work together daily throughout the project.


The most efficient and effective method of conveying information to and within a development team is face-to-face conversation.


Simplicity--the art of maximizing the amount of work not done--is essential.

These all come from the Manifesto for Agile Software Development.

Keeping these in mind, we can say that there may not need to be detailed specs for a user story. The original intent for a user story was a card that serves as a placeholder for a conversation. Originally, much of the conversation was face-to-face, but in today's world there may be phone calls, email threads, video conferences, or other means of communication. The documentation would supplement the conversations.

What you need depends on several factors. You may not need details into use cases, scenarios, constraints, exceptions, and messages for every, or even all, user stories. It may be more useful to focus on delivering the valuable, working software than specifying all of the details up-front when thinking about user stories or use cases for a system. Specifically in Scrum, the act of refinement with the team can reveal what is needed in order to complete the work successfully. The artifacts that you need to create or maintain will be driven by need of one or more stakeholders.

With the principle of a single source of truth for information, it makes sense to keep everything needed to understand the user story in or accessible from a single place. If you are using tools like Asana or Jira, that usually means in the Asana or Jira issues. This could be embedded in the issue or in a different tool that is linked to. I'm not that familiar with Asana, but I do know that Jira has integrations with many other tools to keep information accessible from a ticket and to support traceability between multiple tickets and various types of work, such as user interface designs or code.

As far as when design happens, it usually happens just-in-time. If the design is riskier, there may be efforts done earlier to prototype or research. Again, the specific amounts and types of design will be done as late as possible, within reason in order to allow for reducing the number of unknowns. Design often starts in refinement and comes out in Sprint Planning and throughout the work of delivering the work.

11:26 am July 21, 2021


Hi Thomas,

With that being said, can you please explain where or how a "Functional Analyst" could fit in in such an Agile or Scrum team and methodology ?

Thanks you very much in advance,

Best Regards,

By posting on our forums you are agreeing to our Terms of Use.

Please note that the first and last name from your member profile will be displayed next to any topic or comment you post on the forums. For privacy concerns, we cannot allow you to post email addresses. All user-submitted content on our Forums may be subject to deletion if it is found to be in violation of our Terms of Use. does not endorse user-submitted content or the content of links to any third-party websites.

Terms of Use may, at its discretion, remove any post that it deems unsuitable for these forums. Unsuitable post content includes, but is not limited to, Professional-level assessment questions and answers, profanity, insults, racism or sexually explicit content. Using our forum as a platform for the marketing and solicitation of products or services is also prohibited. Forum members who post content deemed unsuitable by may have their access revoked at any time, without warning. may, but is not obliged to, monitor submissions.