Creating all-inclusive yet clear-cut feature descriptions

Elena Sviridenko
Jul 28, 2017 · 5 min read

The “less is more” philosophy doesn’t work when it comes to describing a new feature in a way that is concise, unambiguous, comprehensive, and yet understood by every member of a team.

On the other hand, thinking that the more you put in, the better narrative it’ll provide, is wrong either.

The balance of wisdom lies in formulating a sharp summary, defining the value carried by a feature, elaborating the ways of proving this value is delivered and complementing the feature with its key artifacts such as mockups, detailed specs, etc.


#1. Summary

Keep it short and right to the point. This allows for its easy

  • remembering, so that everyone can refer to a feature by its title (which clearly says what this feature is about),
  • writing (without shortenings) on the sticky notes,
  • reading on the digital boards (no truncation with ellipsis).

#2. Body

This is where you want to explain what is your team going to do, for whom, and why. And this is where a user story comes into play.

There are plenty of formats for writing it, but my personal preference is this one:
As a {who}
I want {what}
So that {why}

Though, adhering to the format doesn’t make the user story good.

You still need to be careful with formulating the statements, making them concise and purposeful.

Being improperly defined, a user story will stand in the way of delivering a value and shipping a great product to your customers.

I’d recommend sticking to the acronym “INVEST”, suggested by Bill Wake as a reminder of what a good user story is:

  • Independent (of all others)
  • Negotiable (not a specific contract for features)
  • Valuable
  • Estimable
  • Small (so as to fit within an iteration)
  • Testable

By the way, it’s as fun as it’s useful to substitute a role (in the “As a {who}” part of the user story) with the name of the respective user persona. E.g., instead of “As an accountant, I want …”, try “As Clara, I want …”.
Using personas in the feature context creates a strong mental link to that specific representative of your target audience and better helps to “put yourself in your users’ shoes”.

In your feature description, you may want to add how delivering this particular feature helps meet the short- or long-term goals.

#3. Acceptance Criteria

As defined by Microsoft Press, acceptance criteria are the “Conditions that a software product must satisfy to be accepted by a user, customer or the other stakeholder.”

Carefully thought through and clearly defined acceptance criteria help build the right solutions. They add certainty to what a team is doing and indicate when a story can be considered complete and the product working as intended:

  • Express acceptance criteria in clear and unambiguous manner.
  • Write from the perspective of the end-user or customer.
  • Precisely define the expected outcome.
  • State intent, not a solution.
    Give your team freedom to decide how to do it.
  • Use simple and positive language.
  • Don’t be too wordy.
  • Ensure the acceptance criteria are testable.
  • Cover both functional and non-functional requirements.
  • Finalize the acceptance criteria before writing the test cases and starting the development.

#4. Requirements specifications

Always add links to the detailed specifications on the subject.

Specifications are crucial for successful implementation as they carry lots of details which physically can’t fit into the ticket body. And even if they could, this would lead to a reader losing their focus due to the amount of presented information. Therefore, ensure to provide the links to all related specs so that everyone working with a feature can easily access them and apply in their job.

UPD: Though, for the mature and highly organized teams, which create specifications at the time of implementation and then use them rather as a project knowledge base, this point would be just a reminder to add the link (for future reference) before closing a feature.

#5. Visuals

Always add links to the mockups, interactive prototypes, logos and other visuals required to implement the story.

Selectively attach visuals to a ticket: stick to ones illustrating the key aspects of a feature.
Since there may be quite a plenty of related visuals, attaching all of them to a ticket would hamper its overall review (and definitely add to scrolling).

#6. Test cases

Always add links to the test cases.

Business analysts may want to scan through the test cases to ensure the completeness of test coverage.
Also, in the case of an incident in a production environment, it’s easy to spot the relevant user story and attached test cases for further troubleshooting.

#7. Other attributes

It’s important to have the following indicated:

  • Priority.
  • Product component(s) involved in the implementation.
  • Development iteration a feature belongs to, or its due date.
  • Current status (e.g. analysis, design, ready for development, etc.)

#8. Comments

Most of the issue trackers provide the comments section, and it’s important to use it wisely:

  • Keep all the feature-related communication in the comments.
    Even if something was discussed verbally, or in a chat, make sure to summarize in the comments.
    This allows for creating a mini-knowledgebase, sort of. Questions and answers, decisions made (when, by whom, and why), challenges and risks, etc. — whatever happens during the ticket lifetime. Keeping this information in the feature comments makes it easily accessible to everyone.
  • Never use comments for storing the requirements, notes, or changes to the user story or acceptance criteria. If comments affect any of these, take the time to update the relevant ticket attributes, requirements specifications, mockups, or test cases (whatever is relevant).
    Usually, ignoring this rule results in the missing requirements and further rework.

I believe I went through all the core attributes of a good feature. And you are very welcome to work together with your team on extending the list of attributes with those appropriate to your project context.

Elena Sviridenko

Written by

Product Manager & Experience Designer. Passionate about crafting the competitive solutions which deliver ongoing value and pleasant end-to-end user experience

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade