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.

  • This doesn't sound like NLP; it just sounds like ordinary data validation. There are validation frameworks that do most (if not all) of this. – Robert Harvey Dec 14 '12 at 16:14
  • 1
    @RobertHarvey, I am asking for guidance on formally codifying a spec written in natural language into some sort of more formal language suitable for communication in technical circles, and maybe implementation by a validation framework. Nowhere do I ask anything about NLP if you read my question properly. – ProfK Dec 15 '12 at 3:43

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 :)

  • 2
    ...and if you create Gherkin specs, those can be used in BDD frameworks such as Cucumber (cukes.info) or SpecFlow (specflow.org) for automated testing and validation. – mcknz Jan 14 '13 at 23:41

Try modeling it with MVC (model, view, control) objects. Separate data from presentation. For example, you have an education object with fields/properties for high school and diploma. The validator for this object has logic to ensure that education is not valid unless one of these is specified.

  • Yes, I think I'll start with the UI requirements, as this is closest to what the user wants, then map those back into lower level data and logic requirements. – ProfK Dec 15 '12 at 16:34

The big thing you're going to want to ensure - regardless of syntax chosen - is that people are talking about the same thing, and always using the right word for that thing. The domain-driven design term for this is "Ubiquitous Language".

Your example of UI requirements for a dropdown is written in a generic way - someone with no domain knowledge can figure out what is meant by "values from table x". Your difficulty is going to be in converting language from people saying "a dropdown with all of the cities that we have accounts in" into language stating things like "a dropdown whose values are populated from the Cities table, joined to the Accounts table, displaying only cities that have at least one account". But here's the thing - you don't need to specify what table it's coming from. Doing so in your documentation perpetuates the need to translate back and forth.

Instead, encourage all team members to use the same language. In this case that might be something like "a dropdown listing all Account Cities". The developers on the project know what an Account City refers to - but so do administrators, users, testers... not all of whom have any reason to know (or care) about the database structure.

Now - this will require a commitment from everyone on your team. You'll need to engender a culture where someone saying "hang on, when you said 'cities', did you mean Account Cities or all cities in the world?" is seen as a helpful clarification rather than a nitpick. It will require a dedication to rigorous speech that most people don't inherently have. But it can pay off huge dividends long term when everyone in the room is actually speaking the same language, rather than having a thousand little inconsistencies meaning that people aren't on the same page.

If you can adopt such a Ubiquitous Language, translating into Gherkin syntax (or any other) becomes really simple. If you don't, then such a translation will typically fail, because people haven't already developed the habits of mind that enable the precise language required by such a tool.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.