Writing Specifications

Search…
ALWAYS write specifications, while it takes longer upfront, it saves time in the long term! Use a Google Document in the home folder of the project, and ensure that the entire Mäd project for the project has this bookmarked.
This is the Google Document template to get your started, with example sections. You can also find a sample (Red Packet functionality) to see how a specification should be written.
A few articles to get you started:
​Painless Functional Specifications – Part 1: Why Bother?​
​Painless Functional Specifications – Part 2: What’s a Spec?​
​Painless Functional Specifications – Part 3: But… How?​
​Painless Functional Specifications – Part 4: Tips​
​The Process of Designing a Product​
​Designing for People Who Have Better Things To Do With Their Lives​
​Designing for People Who Have Better Things To Do With Their Lives, Part Two​
​Designing for People Who Have Better Things To Do With Their Lives, Part Three​
​Your app is an onion: Why software projects spiral out of control​
Get a list of requirements from the client – Shut up and listen
Never assume what the client wants. This is what a shut up and listen meeting is for.
It is best to have the tech lead and design lead in this meeting if they are available, as they will be able to better address certain points that are raised by the client..
Never assume anything, but have a good understanding of who the client is, their potential requirements. Consider this still as a sales meeting until everything is signed, come prepared with good examples of our previous work.
Let the client speak, write down notes. Don’t write down everything, but do write these down:
Required features
Potential complications
Timeline requirements
Database setup, if there are any third party integration needed
Take the client’s side, and think big picture, so ask the client what, in the short term they want to achieve with the product, and in the long term, how the product will serve the business objectives.
Ask questions from the user’s perspective also. Find out more about the end user with a persona in mind. There may be more than two key users.
Depending on the size of the project, there may be more than one requirement gathering meeting with the client.
Scope and proposal
​Please find a template of the proposal here.​
The proposal is a high-level outline of what will be included in the product, which features and timelines. This information is reflective of the requirements the team gathered from the client.
The proposal should include a covering letter, which justifies why the client should choose Mäd.
It will also include:
Features List
Timelines of each process, broken down by weeks, typically:
Research phase (X weeks)
Design (X weeks)
Development (X weeks)
Testing (X weeks)
Go live date
Backend setup
Version control
Server setup
Database setup
Backups
Cost of the project
Fine prints (e.g. warranty) and appropriate signatures
Setting Up the Project
At the moment, we’re using our good mate Asana to keep our projects in track (soon to be Blue). Once the scope is defined and signed, the PM will have to set up the project in Asana.
Depending on the project, the team will either use a Board or Timeline project. This depends on the type of project and the decision of the PM. However, we prefer to use the Board as it gives us more flexible task monitoring, from one end to the other.
Timelines are good for key milestones. Boards are good for progressing tasks which has plenty of moving components.
All items in the scope, line by line should be included in the Timeline with due dates.
Ideation
In a nutshell, our ideation process is as such:
1.
Set up a meeting with the team to brainstorm
2.
Straight to the whiteboard
3.
List the main usage of the product / navigation
4.
Draw a rough flow
5.
Have everybody on the same page
Set up a meeting
Designers will play a key role in the ideation process, but a member of the development team should also be present to prevent potential development Everests that designers may miss. If possible, a member from the client team can also join the ideation meeting. This will prevent misunderstandings later on and make sure not our team is on the same page, but the clients also.
Allocating a time after WIP is usually a good idea, as everybody is already together. We have plenty of whiteboards in the office, so make sure we use them. List down the objectives of the product, and from then the list of main use cases. From the use cases, we are then able to break down the features and main navigation.
The team can also bring samples from other websites or applications which are relevant to the project.
At times, the team can also ideate via card sorting. We have ample supply of post it notes in the office, so make sure we use them. You can attach post it notes all over our glass walls and windows, or any available space.
Card sorting is useful to categorize potential features together, and to break down features into subfeatures. For example, from the user perspective, a chat feature may contain: sharing, transfer money to friend, send photos, send videos, send location. It is to the team’s discretion if they want to keep some of the features depending on the client request, development time and other complexities.
The first ideation for a feature should only focus on creating an MVP (Minimum Viable Product) with only the core features. Anything else is only jargon.
Once the feature set is ready, and the main navigation is established, then it’s time to wire all those ideas into the whiteboard.
Get some wireframes done
Write a draft of the Specification
The specifications include all information concerning the app. Using the scope document is a good place to start setting up the structure of the specs.
We use Google Docs to write specs, as it is collaborative, saves previous changes so we are able to track them, and it is placed securely in the cloud.
A good specs document covers the essentials of the app without restricting the creative freedom of the designers and developers. It is the template for the app to keep everybody in the same page.
A good specs document is easily readable. Use active voice instead of passive voice whenever possible. Use simple language at all times, as the document is also for team members whose mother tongue is other than English.
It includes the:
Cover
Table of contents
Objective
Actors
Use Cases
Open Issues
Cover
Include in the cover:
Title
Subtitle (optional)
Date created
Specs version
Collaborator
Overview
The specs writer defines the overview of the product, usually in a single, curt sentence. He/she will also define the app and its objectives. For example, Pi Pay is a digital payment that will be used by young Cambodians, 18-35. Take in mind the commercial goals of the client (if available) and how that relates to the product.
Table of Contents
This is plain common sense. Use headings in your specs and make a table of content from Google Docs. This will make the specs much easier to navigate around for everybody.
Actors
Actors could be primary actors and secondary actors. Primary actors include end users or anybody that has direct contact with the end user.
If you have a persona in mind, then this persona can be clearly defined. In the specs, use the name of these personas.
Use Cases
Outline use cases of the app from the point of view of the end user. Specs writer should also take in mind what if situations, i.e. if the end user has no credit on his app, low connectivity, etc.
Remember the wireframes we did in the last section? They will act as your beacon in writing the specs. Complexities will appear as you debunk the wireframes screen by screen, see it as an opportunity to debunk your wireframes.
Use cases example:
User registers through Facebook
Splash screen loads in app
User clicks on “Log In with Facebook”
User allows app to obtain information through Facebook app
User successfully logs in
Use cases will also be used as a template for automated test plans. Find the balance of achieving high-level use cases and having enough details for designers and developers to grasp the details that they need to do their job.
The specs writer should also be familiar with the main navigation of the product and its core functions. He/she will divide the sections into the appropriate feature set, and define the use cases for each.
Include the wireframes in the specs to add clarity.
For example, Pi Pay’s specs will include:
Home Screen
Friends
Chat
Places
Me
Depending on the size of the product and complexity, the writer fleshes out each feature accordingly. For example, for Pi Pay’s Home Screen:
Top navbar
Primary usage icons:
Scan/Pay
Receive
Transfer
Wallet
Springboard icon
Share
Bills
Map
Top Up
Banner
Bottom navbar
Use cases can also be written as scenarios. This is a fleshed out example of how the product works in real life, used by the persona. For example:
“Scenario 1: Mike.
Mike is a busy executive. He is the president of a large, important company that makes dynamite-based products for children which are sold through national chains such as Toys ‘R’ Us. During the course of a typical day, he has many meetings with many very important people. Sometimes a man comes over from the bank to harass him for not paying the interest that was due three months ago on his line of credit. Sometimes another man comes from another bank trying to get him to sign up for another line of credit. Sometimes his venture capitalists (the nice people who gave Mike the money to start his business) visit him to complain that he is earning too much money. “A bonfire!” they demand. “Wall Street likes to see a bonfire!”
These visitors are very upset if Mike has previously promised to meet with them at a certain time, but when that time comes around, Mike is nowhere to be found. This happens because Mike doesn’t know what time it is. At his secretary’s recommendation, Mike signs up for a WhatTimeIsIt.com account. Now, whenever Mike is wondering about the time, he simply logs onto WhatTimeIsIt.com, enters his username and password, and finds out the current time. He visits the site several times during the day: to find out when it’s time for lunch, to check if he’s late for the next meeting, etc. Towards the end of the day, in fact, from about 3:00 p.m. onwards, he checks the site increasingly frequently to see when it’s time to go home. By 4:45 he’s basically just hitting “Refresh” again and again.”
This is taken from Joel on Software – What Time is it?​
Open Issues
Don’t expect your specifications to answer all the questions about the product. In fact, the idea of the specification is to make you think of great questions to ask! There will be some issues which require further thought and questions. However, make sure to follow up on these issues promptly, as it will resolve plenty of issues which will become nastier as the project continues.
Although you may have completed writing some sections, it is also useful to list out the possible issues and potential risks.
Get some designs done
Designing the surface or User Interface is very crucial as this is where the users communicate with the product. At this stage, you should strive for not only great visual design but also usability. These are a few fundamental elements to keep in mind:
Be clear & simple: It is very important that users understand what they are supposed to do or can do with each element on the screen. For instance, users should not guess whether the button is clickable or not. Everything should be clear and predictable. This is why understanding your users are very important; their habit, background and culture will make a huge difference in your design decisions.
Give clear & meaningful feedback: “Every action needs a reaction.” For every interaction that users make with the product, there should be a meaningful response. For instance, if a user types in a wrong password, there should be some form of response letting the user know that the password is wrong.
Be consistent: By keeping your design consistent, you ease the learning process of the user while ensuring that each component feel like they belong together. Users should not relearn how to use the product.
Use visual hierarchy: Great use of typography, color and negative space help user to interact with the product effectively.
Be purposeful: By keeping in mind the goals users try to achieve, you avoid adding unnecessary elements to the screen that may distract users.
Make trade offs: Because there are a lot of factors to consider when designing user interfaces, you should be prepared to make certain tradeoffs in your design to optimize the product. Sometimes, you sacrifice the beauty in order to conform with user’s habits. Sometimes, it is the usability versus efficiency.
Go back and edit specification based on comments
As Joel Spolsky pointed out, specs are living and breathing documents. It is a beast in its own right. With every design changes and development, the writer needs to update the document. This seems like more work, but it will save you the trouble later on when there are confusions on the design.
Use Google Docs comments to point out ambiguity in the specs.
Do a video (if applicable) of the final specification draft.
Specifically if it’s a big feature that requires C-Level or BoD (Board of Directors) approval, it is much better to create a quick video mockup of the feature that then can review, as normal people have better things to do with their lives that read specification documents, regardless of how entertaining you think your writing is.
Domain Pointing and IP Addresses
Bug Reporting Template
Last modified 3yr ago
Copy link
Contents
Get a list of requirements from the client – Shut up and listen
Scope and proposal
Setting Up the Project
Ideation
Set up a meeting
Get some wireframes done
Write a draft of the Specification
Get some designs done
Go back and edit specification based on comments
Do a video (if applicable) of the final specification draft.