We have also started drafting the visuals of the application:
- The wireframes: the black and white interfaces of the application which help locating actions and functionalities;
- The mock-ups: the final interfaces of the application respecting the graphic charter.
However, these graphical elements do not fully illustrate how the application will behave at any given time. They are also subject to interpretation by the developers. In the model above, the indicator « 0/10 » can be interpreted as a button, but it is simply a visual indicator showing that no exercise of the session has been realized by the app user.
#1 – Completing mock-ups
In our example, to display programs with personalized training exercises, it is necessary to take into account the physiological specificities and the medical contraindications specific to each gym member.
Beyond the graphic elements in progress, a number of questions arise:
- Who is the end-user of the mobile application? A gym member? A coach?
- Where do the information and the parameters of displayable exercises come from?
- How to filter the training exercises following the physiological and medical specificities of the user?
All answers cannot be supplied by the wireframes and mock-ups alone.
Functional and technical specifications are the keys to complete graphic elements.
In any application development project (and software development in general), the specifications will allow:
- To determine a common foundation to open discussions with all project stakeholders: it requires to establish a transverse vocabulary;
- To describe the business rules: the functional rules that govern the information display in the application and describe certain user journeys or use cases (error cases, empty views, etc.);
- To identify webservices: how the server containing the data and the application communicate.
This may seem redundant, but an unspecified project is a risky project. All « knowledge » is held by the project historical actors, i.e. the stakeholders present when discussing a specific technical or functional point. Should one leave the project and without specifications, based on our experience the project tends to deteriorate. Communication becomes more difficult, some features are not documented anywhere and no one knows how they work.
Even if nobody quits the project, writing nothing can lead to a situation where everyone understands something different and where the team ends up developing features that nobody wanted.
Solid project foundations are built thanks to smart specifications shared with all the involved stakeholders. The sustainability and maintainability of any project would otherwise be impacted.
#2 – Sharing a common understanding
At FABERNOVEL TECHNOLOGIES, we have implemented functional specifications in the form of a shared spreadsheet document. This document serves as a reference for all project stakeholders.
This document details:
- Features (also called User Stories) to develop: a set of actions that a user can perform via the interface to achieve a goal (view, edit, delete information, etc.).
- The set of exhaustive scenarios attached to it: the steps and the variables conditions while achieving an objective (connected user versus off-line user, etc.).
The specification document also defines the vocabulary attached to the project, containing definitions of major objects handled within the application.
In our example, the document defines:
- A user: a gym member
- A coach: the adviser guiding the gym member during training sessions
- A training program: sessions containing personalized and filtered training exercises for each gym member. etc.
#3 – Building an app which can withstand all situations
Thanks to the specifications, it is possible to describe all the business rules of the application, and in other words the information display restrictions.
Following our example, displaying exercises filtered according to the user’s physiological characteristics and medical constraints is a business rule. This business rule needs to be documented through features and scenarios: the safety of users is at stake!
For a given feature, each scenario is expressed as a sentence that can contain:
- A condition « Given that / Since… »
- An action: « When … »
- A treatment: « Then … »
- A navigation: « Then … ».
Let’s take an example :
Functionality: Display a training program
Scenario 1 – Display a training program for a participant with medical contraindications
[Condition] Since the user is logged in to his or her application
[Condition] Given that the user has at least one medical contraindication
[Action] When the user sees a training program
[Treatment] Then we show him or her the exercises, highlighting the contraindicated ones for him or her (warning sign).
Implementation detail: In the detail of an exercise of the call GET / trainings /: id / exercises /: id check if the contraindications table is filled and if there are common contraindications with those of the connected user.
Scenario 2 – View an exercise program for a female user
[Condition] Since the user is logged in to her application
[Condition] Since the user is female
[Action] When the user sees an training program
[Treatment] So we show her all the exercises of the program specific to her gender
Implementation detail: In the details of an exercise of the call GET / trainings /: id / exercises /: id retrieve the « gender » integer field which is 0 if it is feminine gender or 1 if is of masculine gender
All the features and scenarii are detailed according to this outline.
This format declined by features and then by scenarii is inspired by a test language called cucumber. It is particularly valuable as the test language enables to describe in a methodical and clear manner all the use cases.
The specification document is built with designers and developers and has sufficient granularity to begin developments.
#4 – Specifying the communication with one’s IS
When writing functional specifications in the form of features and scenarios, the product team must question the technical feasibility of what is desired. Thus, one of the first questions to ask is: where and how should we retrieve the information to be displayed on the interfaces?
Some of the information is hardcoded within the mobile application, such as the title of the screens or the contents of the menus. To be modified, it requires to update the application. Other information can come from an external source such as a server within an information system. This information – an account information or a user’s newsfeed, for example – is returned by what are called webservices.
The webservices documentation is historically contained in word or swagger documents (in the best scenario). However, these elements are very rarely kept up to date and the information diverges between the theory of documents and the reality of the webservice.
Also, during the features development of an application, we generally need to test certain situations which leads us to write stubs: static data of example according to the format described in the documentation.
And finally, when webservices are developed, it is important to test the outcome.
Thus, our webservices specification contains three components:
- The documentation: resource definition, query and response formats, error cases, etc. ;
- the generation of stubs: static data;
- The tests.
At FABERNOVEL TECHNOLOGIES we have developed our in-house webservices specification tool that meets the OpenAPI Specification swagger standard. It secures and harmonizes the webservices specification while ensuring good communication between developers, designers, project managers and product owners.
With this tool, any user can quickly:
- Describe the resources: a coach, a gym member, a training program, exercises, etc. ;
- Describe the routes: create a new member (POST/members), edit the information of a member (PUT/members/:id), create a new training program, (POST/trainings), etc.
- Generate stubs (i.e. fictitious data) for developments;
- See what happens in the communication between the servers and the application (i.e., testing the webservices).
We have open sourced the code of this internal tool. Do take a look at it and deploy an instance at your office. We will be happy to get your feedback!
For the record, it was initially an internship research but it quickly became an indispensable tool and a staple for all our projects.
# 5 – Specifications, a must-have for mobile applications!
Specifications are ultimately the foundation of any application. They make it possible to develop a product that is absolutely in line with the expectations of the Product Owner and ensures a product that is more sustainable and maintainable over the long term.
Once your product is specified: all you have to do is develop it.
You will discover in the next article how to build a SOLID codebase following the principles of the Clean Code.
Are you interested by this story?Subscribe to our newsletter