Write In Everyday Business Language

« Table of Contents »
Previous « Avoid Generic Verbs

The Behaviour Specification Handbook

General Tips

Write In Everyday Business Language

A large focus of Behaviour-Driven Development (BDD) is about clear and effective team communication. Not all members of the team have or will have a deep technical understanding. It is in the best interest of the business if everyone is enabled and given the opportunity to understand the logical functionality of each software component.

On a daily basis, the team normally should be communicating with the rest of the business in commonly accepted business terminology. Similarly, the behaviours should be written — as much as possible — in the same accepted style of business language. By doing this, all members of a software development or solution delivery team, including developers, analysts and stakeholders, should be able to understand the Behaviour Specifications.

For instance, say that a business project team engages an internal software development team to develop a subset of a larger solution. The business project team certainly could be interested in reading and understanding the Behaviour Specifications (the test case suite) of the software components that the internal software development team authored. Whether other wider parts of a business would be interested is debatable, and I think that may only apply to businesses with quite a high degree of maturity.

Agree On Business Terminology

The team needs to have a clear understanding about what is commonly accepted business terminology versus technical terminology. In general, communication cannot take place effectively unless agreed protocols are followed. An agreed glossary of business terminology is the basis for an effective communication protocol within a business and is useful reference material — especially for on-boarding new employees.

Such an approach promotes more consistent communication within the solution delivery and support teams — and with wider parts of the business. One tangible, beneficial result of using commonly accepted business language is the minimisation of the costs to train new staff.

Be Professional

Some developers may initially consider working with the Gherkin language and the use of a feature file as a burden. These developers may argue that the usage of the feature file slows them down and that they can much more quickly write automated tests without Gherkin or Behaviour Specifications.

Typically however, such developers are new to the use of Gherkin and have not proceeded past the learning curve. Additionally, some stereotypical technical people can have difficulty in translating technical functionality into common business language for discussion with non-technical people. Because of these reasons, some developers may find they are initially slower in this area, and that can be a cause of personal frustration.

We all need to remember to be professional and look after the best interest of the business. It is in the business’s best interest if the team writes behaviours in their business language, not just for the current set of skills in the team, but for the wide variation of skills that future team members may or may not have. The business language is the lowest common denominator language — not technical terminology.

If the business is primarily product focused or technical in nature, such as one that creates software languages or compilers, then the business language and technical language may be one and the same. By all means, write the behaviours in the business language, which in that case may be quite technical.

Use Natural Language

As a guideline, I highly recommend using the natural language, logical names of artefacts, as opposed to the technical, implementation-specific terminology.

For example, say there is a business service operation for processing credit card payments. In a specification, I recommend writing natural language such as “the service that processes a credit card payment” instead of a more technical implementation name such as “the CreditCardService.ProcessPayment operation”.

Similarly, to refer a particular system in a specification, such as a fictional system named “Insurance Policies 4 Me”, write a natural language, logical name that is appropriate for the business, such as “the insurance policy system”.

Some Technical Terminology Becomes Mainstream

At certain points in time, some terminology that originates from the technical realm does actually make its way into business and everyday, mainstream vernacular. The television and movie industry no doubt have played a huge role in helping to mainstream many technical concepts.

Nothing in the last decade highlights this better than the world of personal and mobile computing. The concept of an “app” or “application” is now common, mainstream vocabulary. From young children to retirees, almost everyone now has access to a mobile phone, tablet or personal computing device, and everyone is familiar with “apps” and an “app store”. Security mechanisms to ensure authorised access to a device — such as user credentials, pin numbers, and swipe patterns — also are now mainstream concepts.

A personally memorable example of this occurred many years ago with my dearly departed mother. One afternoon she came home from a training course at her workplace, and proudly boasted that she had learned how to use their computer system. She then started talking about her “lowgan”. I immediately stopped her and asked what she was talking about — what was this “lowgan”? We had a good laugh together when she said that she and some other staff members didn’t really know who this “lowgan” was, but she knew she had to enter her user name and password when “he” popped up! Of course, between fits of laughter, I quickly explained that it was a “log in”.

What Is Technical Terminology?

Noting that language and commonly accepted vocabulary changes over time, what is technical terminology, and what is not?

That is a good question! The answer is that it depends on each business. What might be considered “technical” in one business, at a specific moment in time, might be common business language right now at another business.

In addition, there are many concepts that began in and are commonly understood in real-life. Many real-life and mathematical concepts have been used as the basis for technical lingo. An example of this is a “queue” of items. A queue is a well understood, real-life concept. Many people stand and wait in queues or first-in-first-out (FIFO) lines at the shopping centre checkout on a regular basis. If a technical team determines that there are messages that need to be queued as part of a solution design, then please say that in the Behaviour Specification, as it is natural everyday language!

Human perception also adds complexity to the discussion. Different businesses, teams and people can have both valid and differing views about how “technical” some “technical terminology” actually is. Every individual has a different perspective and understanding of the world, and their level of tolerance for technical terminology differs.

The Art Of Writing

In the end, finding simple, intuitive and natural words to use when writing a Behaviour Specification sometimes can be thought of as an “art”. There can be a delicate balance between not using language that is too technical or specific, and at the other end of the spectrum, using language that is too generic such that the reader cannot grasp the essence or actual purpose of the behaviour. This balance can be a challenge, especially for novices — but is overcome with an agreed business terminology glossary, some good examples and a little practice.

Tip: It is always helpful to copy the style of existing behaviours that your team agrees are well-written. Take samples of these existing well-written Behaviour Specifications into each behaviour writing meeting and refer to them as necessary. It is often helpful to review these in the meeting to refresh everyone’s memory and help break through any mental blocks.


Next » SpecFlow/Cucumber Is Only The Name Of A Tool