Best Practices for Writing Card Descriptions in Project Management

Tue, 19 Sep 2023 08:28:23 +0700

Card descriptions play a crucial role in project management, particularly in agile methodologies and issue tracking systems like GitHub Projects. They serve as a central hub of information, guiding the team through the completion of tasks or user stories. In this article, we’ll explore best practices for writing effective card descriptions, with a focus on CRUD (Create, Read, Update, Delete) operations, and the use of acceptance criteria.

The Basics: Title and Description

At the core of every card description lies the title and description. These elements provide a concise summary and a detailed explanation of the task or issue at hand.

Issue Status Description Naming

Tue, 20 Sep 2022 05:36:46 +0700

When tracking and managing issues, it is important to clearly define their status to ensure efficient resolution. Below are the commonly used issue status descriptions and their meanings:

New

An issue is marked as “New” when it has been reported but has not yet been assigned to any individual or group for investigation.

Issue Title Naming

Wed, 17 Aug 2022 09:21:20 +0700

User Story Titles

A user story defines a behavior or feature that a solution must implement to meet user needs. The recommended formats for user story titles are:

Issue Type

Mon, 28 Mar 2022 06:07:55 +0700

Business Projects

Business projects typically include the following issue types:

User Story BDD Cucumber CRUD Operations Example

Wed, 24 Nov 2021 10:59:04 +0700

Basic

Feature: Create Employee

  Scenario: WITH ALL REQUIRED FIELDS IS SUCCESSFUL
  
    Given user wants to create an employee with the following attributes
      | id  | firstName | lastName | dateOfBirth | startDate  | employmentType | email               |
      | 100 | Rachel    | Green    | 1990-01-01  | 2018-01-01 | Permanent      | rachel.green@fs.com |

    And with the following phone numbers
      | id  | type   | isdCode | phoneNumber | extension |
      | 102 | Mobile | +1      | 2141112222  |           |
      | 103 | Office | +1      | 8362223000  | 333       |

    When user saves the new employee 'WITH ALL REQUIRED FIELDS'
    Then the save 'IS SUCCESSFUL'

Create Employee

Feature: Create Employee

  Scenario Outline: <testCase> <expectedResult>

    Given user wants to create an employee with the following attributes
      | id  | firstName   | lastName   | dateOfBirth   | startDate   | employmentType   | email   |
      | 110 | <firstName> | <lastName> | <dateOfBirth> | <startDate> | <employmentType> | <email> |

    And with the following phone numbers
      | id  | type   | isdCode | phoneNumber | extension |
      | 111 | Mobile | +1      | 2141112222  |           |
      | 112 | Office | +1      | 8362223000  | 333       |

    When user saves the new employee '<testCase>'
    Then the save '<expectedResult>'

    Examples:
      | testCase                 | expectedResult | firstName | lastName | dateOfBirth | startDate  | employmentType | email               |
      | WITHOUT FIRST NAME       | FAILS          |           | Green    | 1990-01-01  | 2018-01-01 | Permanent      | rachel.green@fs.com |
      | WITHOUT LAST NAME        | FAILS          | Rachel    |          | 1990-01-01  | 2018-01-01 | Permanent      | rachel.green@fs.com |
      | WITHOUT DATE OF BIRTH    | FAILS          | Rachel    | Green    |             | 2018-01-01 | Permanent      | rachel.green@fs.com |
      | WITHOUT START DATE       | FAILS          | Rachel    | Green    | 1990-01-01  |            | Permanent      | rachel.green@fs.com |
      | WITHOUT EMPLOYMENT TYPE  | FAILS          | Rachel    | Green    | 1990-01-01  | 2018-01-01 |                | rachel.green@fs.com |
      | WITHOUT EMAIL            | FAILS          | Rachel    | Green    | 1990-01-01  | 2018-01-01 | Permanent      |                     |
      | WITH ALL REQUIRED FIELDS | IS SUCCESSFUL  | Rachel    | Green    | 1990-01-01  | 2018-01-01 | Permanent      | rachel.green@fs.com |

Get Employee

Feature: Get Employee

  Background:

    Given an employee with the following attributes
      | id  | firstName | lastName | dateOfBirth | startDate  | employmentType | email               |
      | 200 | Rachel    | Green    | 1990-01-01  | 2018-01-01 | Permanent      | rachel.green@fs.com |

    And with the following phone numbers
      | id  | type   | isdCode | phoneNumber | extension |
      | 201 | Mobile | +1      | 2141112222  |           |
      | 202 | Office | +1      | 8362223000  | 333       |

    When employee already exists


  Scenario: GET BY ID

    When user wants to get employee by id 200
    Then the get 'IS SUCCESSFUL'
    
    And following employee is returned
      | id  | firstName | lastName | dateOfBirth | startDate  | employmentType | email               |
      | 200 | Rachel    | Green    | 1990-01-01  | 2018-01-01 | Permanent      | rachel.green@fs.com |

    And following employee phone numbers are returned
      | id  | type   | isdCode | phoneNumber | extension |
      | 201 | Mobile | +1      | 2141112222  |           |
      | 202 | Office | +1      | 8362223000  | 333       |

Update Employee

Feature: Update Employee

  Background:

    Given an employee with the following attributes
      | id  | firstName | lastName | dateOfBirth | startDate  | employmentType | email               |
      | 300 | Rachel    | Green    | 1990-01-01  | 2018-01-01 | Permanent      | rachel.green@fs.com |

    And with the following phone numbers
      | id  | type   | isdCode | phoneNumber | extension |
      | 301 | Mobile | +1      | 2141112222  |           |
      | 302 | Office | +1      | 8362223000  | 333       |

    When employee already exists


  Scenario Outline: <testCase> <expectedResult>

    Given user wants to update an employee with the following attributes
      | id   | firstName   | lastName   | dateOfBirth   | startDate   | employmentType   | email   |
      | <id> | <firstName> | <lastName> | <dateOfBirth> | <startDate> | <employmentType> | <email> |

    And with the following phone numbers
      | id  | type   | isdCode | phoneNumber | extension |
      | 301 | Mobile | +1      | 2141112222  |           |
      | 302 | Office | +1      | 8362223000  | 333       |

    When user saves the employee '<testCase>'
    Then the save '<expectedResult>'

    Examples:
      | testCase                 | expectedResult | id  | firstName | lastName | dateOfBirth | startDate  | employmentType | email               |
      | WITHOUT ID               | FAILS          |     | Rachel    | Green    | 1990-01-01  | 2018-01-01 | Permanent      | rachel.green@fs.com |
      | WITHOUT FIRST NAME       | FAILS          | 300 |           | Green    | 1990-01-01  | 2018-01-01 | Permanent      | rachel.green@fs.com |
      | WITHOUT LAST NAME        | FAILS          | 300 | Rachel    |          | 1990-01-01  | 2018-01-01 | Permanent      | rachel.green@fs.com |
      | WITHOUT DATE OF BIRTH    | FAILS          | 300 | Rachel    | Green    |             | 2018-01-01 | Permanent      | rachel.green@fs.com |
      | WITHOUT START DATE       | FAILS          | 300 | Rachel    | Green    | 1990-01-01  |            | Permanent      | rachel.green@fs.com |
      | WITHOUT EMPLOYMENT TYPE  | FAILS          | 300 | Rachel    | Green    | 1990-01-01  | 2018-01-01 |                | rachel.green@fs.com |
      | WITHOUT EMAIL            | FAILS          | 300 | Rachel    | Green    | 1990-01-01  | 2018-01-01 | Permanent      |                     |
      | WITH ALL REQUIRED FIELDS | IS SUCCESSFUL  | 300 | Rachel    | Green    | 1990-01-01  | 2018-01-01 | Permanent      | rachel.green@fs.com |

Delete Employee

Feature: Delete Employee

  Background:

    Given an employee with the following attributes
      | id  | firstName | lastName | dateOfBirth | startDate  | employmentType | email               |
      | 400 | Rachel    | Green    | 1990-01-01  | 2018-01-01 | Permanent      | rachel.green@fs.com |

    And with the following phone numbers
      | id  | type   | isdCode | phoneNumber | extension |
      | 401 | Mobile | +1      | 2141112222  |           |
      | 402 | Office | +1      | 8362223000  | 333       |

    When employee already exists


  Scenario: DELETE BY ID

    When user wants to delete employee by id 400
    Then the delete 'IS SUCCESSFUL'

References

https://medium.com/@bcarunmail/using-cucumber-datatable-for-crud-operations-7b00f7cac23f

Project Management - Tag - Dimas Maulana