Come for the products,
stay for the community

The Atlassian Community can help you and your team get more value out of Atlassian products and practices.

Atlassian Community about banner
Community Members
Community Events
Community Groups

The art of writing good requirements

Writing Requirements requires both skills and practice. A better requirements document can save your organization a fortune with clear communication between the developer and product stakeholders. This, in turn, reflects across the organization, including greater transparency, lesser rework, and improves productivity.

While every organization has different requirements and methodologies, the fundamentals for writing requirements remain the same.

In this article, I will share a few tips that can help you enhance your requirements writing skills and help you write clear and crisp requirements.

Tip #1 — Understanding User Need or User Story

Understanding the user needs or story or the problem statement clearly is the first step of writing requirements. Therefore, it is essential to follow an equipped framework as these user stories further breakdowns to other artifacts.

One of the standard practices found across industries is to answer the following questions-

  • Who- For who’s benefit are we doing it?
  • What- What are we doing?
  • Why- Why are we doing it?

Thus, by finding answers to “three W” helps your team to get aligned and refine a specific user story or problem statement.

So spend considerable time on collecting and then understanding the user needs.

Tip #2 — Write unambiguous and clear Requirements

Writing clean and clear requirements can save your team and product stakeholders from misinterpretation. It also leads to fewer review cycles to confirm and validate.

Here’s how you can write clear requirements-

  • Avoid using ambiguous words like significant, simple, or user-friendly. These adverbs can not be measured and means different to different people.
  • Avoid combination words like and, or, before and after, in a single requirement. Avoid using these words to ensure your requirement is focusing on only one thing. Short requirement statements are organized and readable.
  • Use consistent terminology throughout the requirements documentation to avoid confusion or assumptions that might not be correct.
  • Avoid using negative words in requirements like “shall not” which can be restated in positive form.

Tip #3 — Requirements should be brief but comprehensive.

While writing the requirements, we should try to be as concise as possible. Requirements should be crisp and short. Long statements or paragraphs may lead to ambiguity and confusion in later stages. Moreover, short statements make it easy to organize the requirements and also enhances their readability.

Tip #4 — Prioritize Requirements

Ask yourself how essential is the requirement? Is it nice to have, or is it mandatory? Prioritize your requirements by using a simple ranking system like Low / Medium / High/ Blocker. This helps your team to focus on critical requirements first.

Tip #5 — Requirements should be Verifiable

The requirement should be written in a way that allows for someone to check if it has been completed or not.

Testers must be able to verify whether the requirements have been implemented correctly or not. The test should either pass or fail. Ambiguous requirements make it difficult to determine whether the test has passed or failed.

Tip #6 — Organize Requirements using Categories or Structure them using hierarchy

The requirements should be categorized so that  we are able to communicate the different levels of requirements to the relevant stakeholders or members in the organization. For example, requirements can be categorized as Business Requirements, Functional Requirements, Non Functional Requirements, System requirements, etc (as per your organizational needs).

With such categorization, the Business stakeholders can concentrate and understand the requirements relevant to them, technical members can focus on requirements relevant to them, and so on.

Defining a well-organized requirements hierarchy is another best practice. Breaking down the requirements (a need) to low-level artifacts (a response to that need) is an efficient way to build requirements hierarchy.

Doing so can help your team to trace requirements, decomposing high-level requirements into granular ones, ensuring validation and verification, test coverage, and establishing traceability.

Tip #7 — Requirements should be separate From Design

While writing requirements, we should not mention any design features or suggestions. At this stage the implementation details or the method of implementation should not be considered. We should focus on the “what” of the system and not on "how". We should not mention any specific technologies or layouts or design rules.

An example of a bad requirement is: The notification from Jira must have relevant information.

An example of a good requirement is: The email notification sent from Jira should include issue Id, Summary, Status and Assignee  details.

Writing good requirements can be intimidating. It takes practice and patience to master the art of writing good requirements.

Since you have reached the end of this article, you already know the awesome tips to write good requirements and now you are on your path to write the best requirements.

Do you have more tips to write good requirements? Do you face any challenges while writing the requirements? Lets discuss in comments.


Good article and it reminds those being forgotten.

It is similar to S.M.A.R.T although this acronym has been used in other context. In my own words in terms of what makes a 'good' requirement document is as follows.

Specific : Requirement has to be stated to the point and no extra, irrelevant words in context. Clear to express needs literally without 'exclamation mark !', not is used to express feelings

Meaningful : Expected outcome should have benefits to the organisation or particular business units. In other words, it has to be measurable for cost and benefit analysis 

Attainable : It means that based on documents contents, interpreted by developers, expected results (deliverables) and objectives should be achieved. Requirement document is a real, living document which tells what users need which is tangible

Recognised : Requirement document should be respected and always can be used as reference when there is loss of attention and lack of customer focus 

Timely : Document has to be reviewed after or even during implementation and it's always good to refer to it regularly to cross check against business environment which changes so quickly. New ideas might come out when document is reviewed again

Like # people like this

Thanks for adding these insightful points @Raymond Fung 

Like # people like this

Crisp and insightful article.

Like Deepanshu Natani likes this

Such a great article it is with attention to details. Great going @Deepanshu Natani 

Like Deepanshu Natani likes this
M Amine Community Leader Sep 26, 2020

great article.

Like Deepanshu Natani likes this

Thanks @M Amine 

Like M Amine likes this

Hi @Deepanshu Natani 

Thanks for your article. Regarding prioritizing, here are some additional thoughts:

  • Keep in mind the differences between urgency, priority and order:
    • Urgency is often based on scope, impact, and time;
    • Valuable and independent requests are prioritized;
    • While the details to implement them are ordered (sequenced) by a delivery team.
  • For prioritizing methods, consider making them relevant, simple/explainable, fast, and repeatable
    • Relevant: the criteria used makes sense for the context of the problem being solved
    • Simple/explainable: the method can be easily explained to stakeholders so they can participate
    • Fast: as new requests appear they can be quickly assessed for priority
    • Repeatable: the method is consistent over time, eliminating the need to repeatedly re-prioritize as practices change, and so building trust with stakeholders

Best regards


Like Deepanshu Natani likes this

Thanks @Deepanshu Natani 

Great article !!!

Like Deepanshu Natani likes this

i really impressed with your guidance no one still in my life gave me these tips that you mentioned in the points feeling real honesty in the article that you published.

Like Deepanshu Natani likes this

Thank you for the additional inputs @Bill Sheboy 

Thank you @Vero Rivas 

Thank you @Halen kila I gathered these points over 8 years of experience working in the requirements management domain :-)


Log in or Sign up to comment

Atlassian Community Events