Technical specification: Project managers, can you speak like developer?

A little miscommunication between a client and a developer can be enough. One additional “tiny” and the whole development process will take one month longer. And will, of course, become more expensive. 
That’s why it got us thinking: Could we avoid it?

Yes, we could!

There just needs to be an interpreter between the client and the developer. Someone who knows the language of both tribes. He understands the client's business, listens to his requirements, and translates them into the technically accurate language of the developers.

Every project manager is this kind of interpreter, who manages the development process of an app or a system. That's why we took our project managers and explained to them how to deliver the client's demands to us in a way that every developer can understand.

We taught them what the word entity means and what is the difference between a 1:N and an N:N connection.
Thanks to that, they can clearly and accurately describe what the client needs and avoid misunderstandings and overpricing of the app.

And that’s also what we are going to teach you right now.

Who should read today's article?

Today’s article is for everyone who is dealing with an app or a web development:

• Project managers.
• Sales managers.
• Tech teams managers who want to make their work easier.
• Or even the clients: companies that already have or are planning to have their app or a system developed.

After reading this article, you will know how to technically describe a client’s demands for an app. You will take a look at it through analytic eyes and learn to translate the client’s demands into developers´ language so that there would be no misunderstanding.

Don't worry, we have skipped all complicated terms, UML, ERD, diagrams, or models. Let´s start simply.

Technical specification = data-oriented + functional (and now it gets interesting)

We have simplified the whole thing into two basic views:

• Data-oriented specification (what data we will be working with)
• A functional specification (what is supposed to happen with the data)

To satisfy also UML puritans: What are we talking about? We are talking about the basics of entity diagrams (ERD, if you will) and the UseCase.

But back to the human language.

Data specification

Entities

The basic question developers ask is:“ Which data do we work with?”.
That’s where the term ENTITY comes into play.
The entity is a data representation of the real object. It can be physical (user) or also abstract (order). 
If we can name more things by one word, it is likely an entity. If John, Richard, or Thomas log into our system, they will represent the entity called User. 
Let’s say we are planning to develop an e-shop. Our project manager and the client will probably have the entities like Order, Payment, Product, Category of product, or User in their mind.

Attributes

We already know that there should be an entity called a User in the system. But the developer also needs to know which user data should be stored. That’s what we call attributes. For every user, we want to store for example Name, Surname, E-mail, Password, and the Registration date.

Connections

Okay, but what if the order from the e-shop contains products in its shopping cart? Are they attributes? No, they are not. This is a connection between more entities. These connections are the key in estimating the workload of the project (and therefore its price too).

This is the point where we often have a request for a change. It looks like a small thing but it can take even a few days. That’s why it is important to define well connections right at the beginning.

We define three basic types of connections 1:1, 1:N, N:M.

1. 1:1 connection says that one A-type entity can only be friends with one B-type entity. For example, every car has only one engine and every engine can only be in one car.
2. 1:N connection says that one A-type entity can be friends with more B-type entities but the B-type entity can be a part of only one A-type entity. For example, Manufacturer (A) produces multiple products, but each Product (B) has only one manufacturer.
3. The N:M connection is called “many-to-many”. So every A-type entity can have more B-type entity friends and vice versa. For example, each category contains multiple articles and each article can be found in multiple categories.

Why do you need to know this?

One example is better than five hours of explanations.

Recently, we have implemented a coffee network office management system. So we had an office and a manager entity. 
The basic task was: Each office is managed by one manager. The Manager may manage more offices.
So, it was a typical 1:N connection. Unfortunately, right after the system was released, a new demand occurred: “managers want to substitute and control one another, so the system must have the function "Each office has more managers".
It was a change of the connection type from 1:N to N:M. It looks simple, but it has added a lot of work for us and made the development unnecessarily expensive.

So keep in mind:

Description: 3 types of connections between entities

Functional specification

Before we start a new application, we need to know what features the application should be able to do. So we are interested in WHO can do WHAT and what are LIMITATIONS.

We have already explained the data model (entities, attributes, constraints). In addition to it, we also need to know the so-called Personas. That is users who act in different roles. For an e-shop, this would be the customer, the operator, the campaign manager, and the owner. These different people have different rights and operations.

Does that sound complicated? It isn't. All we need is a simple bullet list.

Dejme tomu, že připravujeme jednoduchý e-shop. Řekli jsme, že budeme mít entity Produkt, Objednávka, Zákazník. Funkční specifikace pak bude vypadat například takto:

• Product
  • Add / edit /delete – Administrator
  • Add to order (=buy) – Customer (registered)
• Order
  
  • Create/ send – Customer
  • Change status, cancel – Administrator
    
    • Note: when the status is changed, an email is sent to the customer

It's that simple.
Now that you know the basics of the technical specification, you're ready to translate client requirements to developers. And that such an interpreter is priceless. It prevents confusion and misunderstandings that make development more expensive.

While you're with us: have you read the interview with agile coach Libor Beněk? Learn why an agile approach pays off for all companies, not just development companies.