Writing an App Specification

In this video I talk about what makes a good specification for building an app. In these times of agile development practices, it’s tempting to just go ahead and write the code from simple requirements, and then refine during short iterations with the users and stakeholders. This may actually work for the development, but already when starting to test it becomes difficult without complete requirements.

There are many practices for documenting the architecture and requirements of a solution and the most common methodologies (e.g. RUP, TOGAF, etc) divide them into a number of different documents, which is the main reason that many promote a simpler approach. In an attempt to find a middle path, I will show you a template that I’ve created by merging the best from the common methodologies, but still keeping everything in one single document. The specification template consists of mainly three parts, and they are the conceptual, the logical, and the physical views of the solution.

The conceptual solution answers the question “what?” as in “what the mobile solution will do?”, and include the functional and non-functional requirements. It starts with an overview figure and description, followed by the user stories (or simplified use cases). The user stories are complemented by screen mockups of all the screens in the app. If a screen is very complex, which should be avoided if possible (apps should be simple), several mockups may be needed for that screen. Following the user stories is a brief description of the service calls and data that the app will use, and finally comes the non-functional requirements (e.g. security, availability, etc). The conceptual solution is very useful during the implementation, and in the creation of test cases to verify the quality of the solution.

The logical solution answers the question “how?” as in “how will the solution be implemented?”, and describe the main parts of the solution, but without being specific on what technologies and products to use. It starts with a figure followed by a description of the different parts of the solution. The logical solution is essential when it comes to compare and select the final physical solution. For example, it can be shared with different suppliers, which can come back with a suggested physical solution based on their products.

The physical solution answer the question “with what?” as in “with what will the solution be realized?”, and describe the actual products and technologies used as well as solution details (service interfaces, database structures, etc). It also starts with a figure that is similar to the one in the logical solution, but here each part of the solution is also specified with the actual technology or product that will be used to realize that part. In the description of the figure, all details about each technology and product are provided (like edition, version, etc). Then service interfaces are documented with request format, parameters and their data types, returned entities and their data types, response and error codes, etc. The database tables are specified with attributes and their data types, primary keys, etc.

An important point about a document like this is to ensure that it’s a living thing throughout the project, and therefore I recommend storing the document using a cloud service (e.g. Google Drive). When requirements or technical solutions change, make sure that the document is updated so that it’s aligned with the implemented solution. This way, the document will automatically become the system documentation.

So there you have an example of what a good specification for building an app can look like.

You can download the template.