A technical specification template for describing a user facing systems such as web or mobile apps.

spec_template.md

Spec template for user facing systems

Table of contents

• Table of contents
• Summary
• Conceptual data model
  • User
  • Role
• User stories
  • x.x Title
    • x.x A more specific title
  • 1.0 Accounts
    • 1.1 Registration
• Components
  • Component
  • Navbar

Summary

Give a summary of what you're building. With greater sentences, both in quality and quantity, than the ones used here.

Conceptual data model

Describe what the entities in your system look like. This is a conceptual model - how you think of the data in your head or would draw on the back of a slightly stained napkin.

Examples:

User

• Name
• Email
• Roles

Role

• Name
• Description

User stories

User stories describe ways an actor can interact with the system and how the system behaves and response. Each story should be manually tested for quality assurance and be automated. The granularity and contents of individual stories varies based on the complexity of the requirements, the author's subjectivity, and lastly their diligence. The contents of the example stories below are merely guidelines. Your goal is to describe the story accurately covering all the details, yet the truth of the matter is that some stories just don't have many (or need) many details.

Examples:

x.x Title

x.x A more specific title

Quick summary of what this story is all about. Omit if self evident.

Actor: Who is interacting with the system. Is it a registered user, a user with a specific role, so on and so forth.

Trigger: Is there a certain action which triggers this story to take place?

Requirements: Describe behavior and conditions for that behavior.

Flow: How does the process flow?

The above examples are fairly granular. At times it makes sense to conflate some of the descriptors together, especially Triggers, Requirements, and Flow based on the complexity, or lack thereof, of your story.

Example

1.0 Accounts

1.1 Registration

In order to become a member of the site a user must register. The user is presented with a registration form.

Actor: Unregistered user.

Trigger:

1. Actor navigates to /register.
2. Actor is presented with a registration form if they try to perform an action which requires registration.

Requirements:

1. Fields
   • Email - required, unique
   • Name - required, unique
2. If this is the first user in the system they must be assigned the Administrator role.
3. On success
   • Actor is redirected to the home page
   • In the navbar the sign in and registration actions are replaced with the user's name and a logout action.
4. On failure
   • If validation error, trigger error state in input field and show the error.
   • If user or email exists, show the error on the form.

Flow:

1. Fill out the form fields.
2. Submit form.

Including the Flow is overkill in this scenario.

Components

The different pieces of your system.

Component

Describe the component.

Behavior:

1. The component behaves like this if these conditions are met.
2. The component can also behave like this other conditions are met.

User stories:

• List the user stories which involve this component.

Example

Navbar

The navbar contains the a logo, site name, and account related fields.

Behavior

1. Visible when scrolled to the top of the page.
2. Invisible when scrolling downwards.
3. Visible when scrolling upwards but with a differently colored background.

User stories:

• 1.1