Writing Features

Writing features is an essential process when it comes to Software Engineering/Development. In the end, it is a features what makes your piece of software valuable for your users/customer. There are different methodologies and techniques we can use in order to make the process easy and clear for all the involved parts: Engineering, Product, Marketing, Business, thus, the entire Organization.

Issue Types

Issue types distinguish different types of work in unique ways, and help you identify, categorize, and report on your team’s work. They can help you and your team/s to build more structure into your working process.

These are the most standard ones (although you can personalize them independently of which Isuues Tracker you are using):

  • Story: A user story is the smallest unit of work that needs to be done.
  • Epic: A big user story that needs to be broken down. Epics group together bugs, stories, and tasks to show the progress of a larger initiative. In agile development, epics usually represent a significant deliverable, such as a new feature or experience in the software your team develops.
  • Bug: A bug is a problem which impairs or prevents the functions of a product.
  • Task: A task represents work that needs to be done.
  • Subtask: A subtask is a piece of work that is required to complete a task (it is actually a child of a task). Subtasks issues can be used to break down any of your standard issues in Jira (bugs, stories or tasks).

Tips and Tricks

Writing features is not straightforward: many different people profiles are involved and they ALL should understand what they mean (their description). Here are some useful tips, which could help in order to write better Feature/Functionalities/Issues/User Stories:

  • Create Features in a collaborative way. You might start by yourself but involve takeholders as much as possible without creating a communication overhead.
  • Users Come first. A Feature/User Story describes how a potential user utilizes the functionality.
  • Keep Features simple and concise. As mentioned, they should be short and easy to understand using a commong language.
  • Start with Epics. You might start simple and move towards complexity, you get the global picture and afterwards you can refine it by breaking it down into smaller Features/User Stories.
  • Refine the Stories until they are ready. A good technique would be by using a Product Backlog Refinement Session.
  • Add Acceptance Criteria. This is a must since it will allow you to describe the conditions that have to be fulfilled so that the story/feature is done.
  • Keep everything visible. Use a board or a tool like an Isuues Tracker which is accessible and visible for everyone in the organization.


Gherkin is a Business Readable, Domain Specific Language created especially for behavior descriptions. It gives you the ability to remove logic details from behavior tests, which turns it into a language that could be understood by anyone without getting deep into implementation details (from an Engineering Perspective).

It serves two main purposes:

  • Project’s documentation.
  • Automated tests.

These features make Gherkin very powerful, but in my experience, it is also very opinionated so in the next sections I will provide a bunch of examples to better understand its syntax.

Syntax and Example

The most basic building block consists of a feature description plus different scenarios. Every scenario consists of a list of steps, which must start with one of the keywords Given, When, Then, But or And (or localized one).

TIP 1: Gherkin responds very well to BDD by using an approach GIVEN-WHEN-THEN.

FEATURE: User Login
  In order to use our mobile client, users should be 
  able to authenticate.  

  SCENARIO 1: Login with email 
    GIVEN there is a login screen
    AND I have introduce my email and password
    WHEN I press the login button
    THEN I should be authenticated
    AND taken to the welcome screen

  SCENARIO 2: Login with phone number 
    GIVEN there is a login screen
    AND I have introduce my phone number and pin
    WHEN I press the login button
    THEN I should be authenticated
    AND taken to the welcome screen

TIP 2: I tend to use Gherkin keyboards in uppercase in order to distinguish between common language and DSL.

Further Checking