Formalizing a requirements spec written in narrative English

documentationRequirementsspecifications

I have a fairly technical functionality requirements spec, expressed in English prose, produced by my project manager. It is structured as a collection of UI tabs, where the requirements for each tab are expressed as a lit of UI fields and a list of business rules for the tab.

Most business rules are for UI fields on a tab, e.g:

  1. Must be alphanumeric, max length 20.
  2. Must be a dropdown, with values from table x.
  3. Is mandatory.
  4. Is mandatory under certain conditions, e.g. another field is just populated, or has a specific value.

Then other business rules get a little more complex. The spec is for a job application, so the central business object (table) is the Applicant, and we have several other tables with one-to-many relationships with applicant, such as Degree, HighSchool, PreviousEmployer, Diploma, etc.

  1. One such complex rule says a status field can only be assigned a certain value if a many-side record exists in at least one of the many-side tables. E.g. the Applicant has at least one HighSchool or at least one Diploma record.

I am looking for advice on how to codify these requirements into a more structured specification defined in terms of tables, fields, and relationships, especially for the conditional rules for fields and for the presence of related records. Any suggestions and advice will be most welcome, but I would be overjoyed if i could find an already defined system or structure for expressing things like this.

Best Answer

You could formalize these requirements using Gherkin syntax, for example:

Scenario: Entering nothing into the name field
    Given I am on the main data entry tab
    And I have not entered a value into the name field
    When I click OK
    Then I should be prompted to input a value into the name field

Screnario: Name field input too small
    Given I am on the main data entry tab
    And I have entered a value into the name field that is less than 10 characters in length
    When I click OK
    Then I should be warned the name field must be at least 10 characters long

The idea behind gherkin is that requirements (somtimes called "Given, When, Then") are split into features, and each feature is split into one or more scenarios. Each scenario is codified with preconditions (Given some context which sets up the scenario into a known state), actions (When I [the user] take some action) and assertions (Then some observable side effect or goal should be achieved).

There's a lot of information on the net about Gherkin style specs and how they help to formalize and codify requirements, improving communication and understandment* between developers and domain experts.

* yes this is a made up word :)

Related Topic