Tutorial: high-level specification

Learn how to describe your high-level specification along with best practices.

Before kick-starting your Uniscale journey you should have:

When this is done, you are ready to follow the guide below on how to build better software!

Introduction

The specification, or functional requirement specification, is where you specify the overall idea. This includes an introduction, the main challenge, why you are going to solve this, and on a high level your approach to solving this.

This part is done from an abstract view, meaning that it is not about solving the actual problem, but rather carefully explaining what the problem is and what the desired outcome is.

This is typically defined by the Founder, Visionary, Product Owner, or someone who understands the solution.

Best practice

Cater to your audience

Aim for a short and concise description. Cater the message to your audience whether this is for internal or external stakeholders.

Tip: Make use of our Generative AI to help improve your writing. Learn more here: Tutorial: Using AI in Specification

Keep it at an abstract level

Focus on describing the key challenge and purpose of your specification and leave the concrete steps to solving the issue for later. This will help you make sure that people are aligned on the overall goals and that your solution will meet the customer's requirements.

Describe your high-level specification

To help you get started, here are some inspirations for what to include in your specifications.

See template: Template: Solution description

What - Describe what you're building
  • Short description: Explain in a few sentences what your product is doing.

  • What are the high-level functionalities and features of your solution?

    • Come up with 3-5 bullets that explain overall what your solution will be doing.

    • What are the main requirements from your actors?

    • Try to write in a few sentences how you will solve this problem without going into detail.

Why - Purpose and motivation: Why are you building this solution?

Describe to your audience what the purpose of your solution is.

  • What is the purpose

  • What value does it bring?

  • What are the desired outcomes that you want to achieve?

  • What is your motivation for building this solution?

  • What are the struggles and challenges that you see for example in the market?

  • What are the problems or needs that people have?

  • Why are we the right people to solve this problem compared to others?

Who - Roles that will be using our solution

Start by listing all the actors that will be involved in your solution. Here is some inspiration:

  • Different roles and personas

  • Partners

  • Distributors

Now can you group the listed actors based on eg. their type and interactions with each functionality?

This is to identify patterns of your actors, like roles and people that interact with the solution, for example, the end-users (customers), and stakeholders like system administrators, suppliers, third-party contributors, etc.

Data sources - Where does your data come from?

List here where the different types of data will come from. Here is some inspiration:

  • Manually inputting data

  • Integration with systems or service providers

  • Does the customer have to provide their details or personal information?

Create and describe your first modules

Before creating modules, we recommend reading our guide for best practices: Best practices for creating modules

Module description

The description of your module is where you describe the purpose and intention for this specific module.

💡 Tip: You can re-use the relevant information you described in your high-level specification.

Here are relevant things to include:

  • Intended functionality for the specific module.

  • What is the exact action that this module intends to achieve?

  • Detailed explanation of what this module is supposed to do and how it proposes to achieve it

  • Actors: Who is going to interact with this module?

Break your modules into pages for grouping functionality

Pages are an element for structure, where you can organize and group your functional use cases. Often used (if needed) when you have locked in the first revision.

You can read more about Pages here: #page

Functional use cases - high level definition & user story
  • This is the high-level behavior: a clear description of the high-level functionality intended for the user (this usually entails an action/ taking the user from point A to point B

  • A good logic to follow is that you should describe the functional use case with:

    • Define the actor and their needs.

    • Describe what each actor wants to achieve.

    • Define their desired outcome.

  • Examples: House cleaning app: As a house owner, when my house is dirty, I want to book a cleaner, so that my house is cleaned.

You can read more here: Functional use case

Add Acceptance criteria to your Functional use cases
  • Describe what this is and how it will work

  • Definition: a list of qualifications that the functional use case (UX flow if detailed specification?) needs to fulfill


Next steps

Last updated