news channel 5 school closings clarksville tn

Bytesize Adventures
Crafting bite-sized digital worlds

  • Home
  • Experiments
  • About

App Development – The Design Document

Last week I discussed my plan for producing my Coffee App and gave a brief overview of the idea. This week, it’s time for the next step in my master plan – the design document.

What’s the point of the design document?

Documentation, like project management, is not sexy – at least not to any developers I know (past making sarcastic comments in the code itself). It does however have a valuable role to play.

The design document should aim to clear up potential design issues before development begins. It presents the features that will exist in the App and explains there significance to the experience. For my Coffee App, I want the document to be comprehensive without dictating the technical details of the implementation. I may well deviate from it and add new ideas, during both the graphic design and development, but it gives me an anchor point. Something that I can refer back to during development when I feel that the App is deviating from the original idea.

The other thing the design document forces you to do is think through the details. When I was writing this document I hit a number of stumbling blocks that forced me to rethink certain aspects. I’ve narrowed the focus of the App to concentrate on what is important – the inputting of tasting notes.

What goes into the document?

I say, go with what your heart tells you. I’m sure there are loads of examples out there on the internet but, as a solo developer, what you’re trying to create is something that you will find useful. I don’t think there’s a need to add content just because you feel you should. I’ve split my document into sections, here’s a little bit about them.

In a few words

Literally a single sentence that captures what the App does. The elevator pitch, if you were only going up a single floor. This is the sentence that I want to be going through my head throughout the various stages of the creation of this application.


Its all about the users! You need to know who is going to use your App. Hopefully the profile of this person can pretty much come from yourself if you’re building an App you’d use (and I hope you are). This is just a few paragraphs to act as a useful reminder as to who your App is for. In this instance I actually have two subtly different audiences in mind. I think this is fine since they still center around a common theme (but there is some potential for design conflict that I’ll have to keep an eye out for). The wireframes should help me resolve some of this.

The Experience

A few paragraphs on what its like to use the App. This is essentially a slightly more detailed overview of the App to highlight the “feeling” of the core features. I’ve used it as a chance to express the compelling aspects of the App and to remind myself of the overall experience I’m trying to achieve.

How it will be used

It seems vitally important to consider when and where a user will be interacting with your App. I’ve created this section of the document to detail a few scenarios when I think the App will be used. They’re all slightly different and focus on individual features of the App. This is going to be useful to refer to and literally act out the usage of the App.

The App needs to be tailored in such a way that it complements these experiences and makes allowances for the environment in which they take place. For example, for areas of the App where the user will be using features at home, I can afford to present a more visual, absorbing experience. However, for features that are used when the user is out and about, the experience needs to be quick and easy.


For this section of the document I’ve listed all of the core features of the App. I’ve detailed their functionality and added some suggestions as to how they might work. Many of the uncertainties here will be ironed out in the wireframes and workflow. Anything remaining after that will ultimately be decided during development and user feedback. I’ll be referring to this section regularly during development to complement the wireframes that I’ll be building from.

The real thing

Its not fair to have you read all of that and not show you the real thing. So, with the theory out of the way, here’s the actual design document ive created for my Coffee App.

Coffee App

Design Document

Author: Christopher Waite
Date: 12th February 2011

In a few words

An App for recording your Coffee tasting experiences and sharing them with others.


The intended audience for this App is someone who loves Coffee and wants to record their tasting experiences for the Coffees they try.

A secondary potential audience is the casual Coffee drinker looking to learn more about appreciating Coffee. Where possible the App should guide the user in adding appropriate tasting notes.

The Experience

The primary experience is around easily recording your tasting experiences. This needs to be visually appealing and extremely intuitive (almost addictive). You’re adding buzzwords that represent your experience whilst you’re tasting the Coffee, therefore interaction needs to be a breeze. Any barrier here will ruin the App experience and prevent uses from returning.

The Coffee Cupboard is the users point of entry and needs to be visually strong. It has to feel personal to the user and provide an experience unique to this App.

The “cellar” of Coffees you’ve tasted and the search feature are where a lot of the power lies. This part of the App is nearly needs to be responsive first and foremost.

How it will be used

Example 1: A user walks into the kitchen and makes a Coffee. When they come back to their seat, they take out their iPhone and tap on the App. They tap the Coffee they are tasting (if its already in their cupboard) or add a new Coffee if they’re tasting for the first time. As they sip their Coffee they enter words that are relevant to how the Coffee tastes.

Example 2: A user wants to tell a friend about a Coffee they are tasting. The user opens the App, navigates to the Coffee and “shares” it with the friend. The friend receives an email (other sharing options may be available) with details of the Coffee and tasting notes along with a link to import it into their own “cupboard”.

Example 3: A user is in the shops, or surfing online, and wants to buy some Coffee. They take out their iPhone, open the App, and search “My Coffees” for coffees that they liked, rated highly, and had specific flavours. Upon finding a Coffee they can continue their purchasing knowing they’re getting something they will enjoy.


1) Coffee Cupboard

A hub that collects the Coffees you are currently drinking. These may be Coffees in your cupboard (Beans or Grounds), Coffees in a Cafe, or one-off tastes.

The Coffee Cupboard is like a live stream of you Coffee tasting activity. It may also be the collection point for your shared Coffees.

This hub should be customisable to allow the user to make it their own.

2) My Coffees

This is the guts of the Coffee App. All of the Coffees the user has ever tasted are stored here. Coffees that the user has finished with (Archived) will be moved from the Coffee Cupboard to this section.

This needs to be presented in a manor that is easy to navigate. Flipping through past Coffees should be an easy and pleasant experience.


The search lets the user easily find previous Coffees that they have tasted. Important search criteria will be Coffee name, rating, and important words from the tasting notes.

4) Sharing

Sharing coffees is part of the core experience. This should be easy and provide various sharing options such as twitter, email, facebook, etc.

Viewing shared coffees should not rely upon the App but owners of the App should be able to fully import the coffee.

5) Viewing Coffees

Viewing coffees should be pleasant and visual. Tasting notes should be easy to see and understand at a glance. The user should also have the ability to mark a Coffee as a “Favourite”.

6) Adding Coffees

Adding a coffee should be fast with minimal required fields. However, there should also be the ability to add comprehensive information if the user wants to.

Coffee name, country, region, farm, place purchased, rating, tasting notes, preparation notes, an icon to represent the coffee on the cupboard page. Maybe the ability to add a photo.

7) Recording tasting notes

Recording tasting notes should be incredibly easy and lots of fun. Primarily text based, simple entry of single words (big, bold, fruity etc). Perhaps a grid of commonly used descriptive words will aid in speedy and enjoyable entry. Maybe I could allow voice notes too and even pictures.

This experience should also potentially be guided to help the user in appreciating flavours and recoding appropriate words.

To complement the tasting notes is the ability to rate a coffee – a simple 5 star scale.

9) Preparation Notes

The ability to add preparation notes would be a really nice addition. This could just be a simple text notes field – with the ability to add multiple sets of prep notes along with rating them. This will help the user to identify preparations that worked to get the best from the particular coffee.

Next Week

Next week, wireframes and workflow. These will complement the design document and will act as the blueprint for the creation of the graphics and development of the App. Next weeks post will also be much more visual. See you then.

This post is part of a series that will follow the design, development, and release of my Coffee App. You can view the other posts here…

Part 1 – Doing it properly
Part 2 – The Design Document (You are here)
Part 3 – The Wireframes
Part 4 – The Artwork
Part 5a -The Code (Xcode, GIT, and Core Data)
Part 5b – The Code (Coffee sharing and Camera functionality)
Part 5c – The Code (A change in workflow)
Part 6 – The testing
Part 7 – The Final Artwork
Part 8 – The Marketing
Part 9 – The Launch
Part 10 – The Numbers
Part 11 – The Postmortem
(Bonus) Part 12 – A review of the process

(thumbnail image courtesy of kjfnjy )


  1. chrismwaite says:
    February 19, 2011 at 4:00 pm

    App Development – The Design Document – … #iDevBlogADay

  2. hermanjakobi says:
    February 19, 2011 at 4:37 pm

    RT @chrismwaite: App Development – The Design Document – … #iDevBlogADay

  3. rizergames says:
    February 19, 2011 at 4:54 pm

    RT @chrismwaite: App Development – The Design Document – … #iDevBlogADay

  4. Pingback: Tweets that mention App Development – The Design Document | Bytesize Adventures —
  5. GeorgeSealy says:
    February 19, 2011 at 10:47 pm

    RT @chrismwaite: App Development – The Design Document – … #iDevBlogADay

  6. MarkusN says:
    February 19, 2011 at 10:48 pm

    RT @chrismwaite: App Development – The Design Document – … #iDevBlogADay

  7. frederictessier says:
    February 19, 2011 at 11:57 pm

    RT @chrismwaite: App Development – The Design Document – … #iDevBlogADay

  8. sycx says:
    February 20, 2011 at 12:44 am

    RT @chrismwaite: App Development – The Design Document – … #iDevBlogADay

  9. LittleTodd says:
    February 20, 2011 at 1:22 am

    RT @chrismwaite: App Development – The Design Document – … #iDevBlogADay

  10. appdk says:
    February 20, 2011 at 7:42 am

    @chrismwaite I know someone who works at a certain “big” iphone game studio ( acquired by some jap co ) that do not use game docs.

  11. chrismwaite says:
    February 20, 2011 at 10:03 am

    @appdk I’m sure. I certainly don’t believe that design docs are required for all projects.

  12. Luke says:
    February 27, 2011 at 10:26 pm

    Great series, thank you.

  13. Pingback: App Development – The Testing | Bytesize Adventures Blog
  14. Pingback: App Development – The Final Artwork | Bytesize Adventures Blog
  15. Pingback: From Idea to App store in 6 months | Bytesize Adventures Blog

Leave a Reply Cancel reply

This site uses Akismet to reduce spam. Learn how your comment data is processed .


  • App Development
  • Design
  • Development Diary
  • Featured
  • Game Design
  • iDevBlogADay
  • News
  • Reviews
  • Tangents
  • Virtual Reality
  • Weekly Update


a-frame App app design app development apple App Store app store submission art artwork astro noughts brainwave cardboard dungeon christmas cocos2d coffee coffee app coffee cellar Design devlog explorer game design game development game jam icarus ideas iDevBlogADay inkscape interactive fiction marketing merlot mini mob moai music new game PPRPG professional review project management promotion rocket santa sales screenshot Star Fusion story text adventure video virtual reality vr webvr weekly update xcode

Latest Comments

  • CheeseBurg – Could you update this for Ubuntu 16.04 and the GitHub instructions? I have no experience installing stuff like this on linux and I have been having is…
  • Arnav – Have you checked out yet? Really cool website with top features and great content! some free tracks in there too….
  • bu95bunny – still can’t get it, cuz i keep getting error 2 with any ways/VMs/Linux distributoons/GCC versions etc. to build it -.- Can somebody who have built Ge…
  • yoyz – Hi, thank you for this tutorial which is well made. For me which run on debian 8.0 x86_64 I had to do some tweaks :Before building gendev : $ …
Content © 2018 Bytesize Adventures. Website design by Christopher Waite. | RSS Feed

Skip to main content
Start reading the article
Jump to list of all articles

Smashing Magazine


Search powered by our good friends at Algolia

Browse All Topics

  • Accessibility
  • Android
  • Animation
  • Apps
  • CSS
  • Design
  • Design Patterns
  • Design Systems
  • E-Commerce
  • Freebies
  • Graphics
  • HTML
  • Illustrator
  • Inspiration
  • iOS
  • JavaScript
  • Mobile
  • Pattern Libraries
  • Performance
  • Photoshop
  • Plugins
  • React
  • Responsive Web Design
  • Service Workers
  • Sketch
  • Typography
  • UI
  • Usability
  • User Experience
  • Wallpapers
  • Web Design
  • WordPress
  • Workflow

About The Author

Eduard is CEO and Co-founder at the mobile agency Polecat . With a development background, he mostly serves as first point of contact with clients, helping them …
More about Eduard

  • Leave a comment

From Idea To Development: How To Write Mobile Application Requirements That Work

  • 11 min read
  • Mobile ,

    Process ,

    Wireframing ,


  • Share on Twitter or  LinkedIn
A postcat. Sign up for our Smashing Newsletter.

Smashing Newsletter

Upgrade your inbox and get our editors’ picks twice a month.

With useful tips for web devs . Sent 2× a month.
You can unsubscribe any time — obviously.

  • Start building powerful, reactive apps now.

  • Earn Your Master’s Degree Online

Why write requirements? Well, let’s imagine you want to produce a mobile app, but you don’t have the programming skills. So, you find a developer who can build the app for you, and you describe the idea to him. Surprisingly, when he showcases the app for the first time, you see that it is not exactly what you want. Why? Because you didn’t provide enough detail when describing the idea.

To prevent this from happening, you need to formalize the idea, shape it into something less vague. The best way to do that is to write a requirements document and share it with the developer. A requirements document describes how you see the result of the development process, thus making sure that you and the developer are on the same page.

In this article, we will outline the most common approaches to writing requirements documents. You will learn the basic steps of writing mobile application requirements and what a good requirements document looks like.

Further Reading on SmashingMag:

  • What You Should Know About The App Design Process
  • Creating Wireframes And Prototypes With InDesign
  • The Skeptic’s Guide To Low-Fidelity Prototyping
  • UX Sketching And Wireframing Templates For Mobile Projects (Free Download)

Meet Smashing Book 6 — our brand new book focused on real challenges and real front-end solutions in the real world: from design systems and accessible single-page apps to CSS Custom Properties, CSS Grid, Service Workers, performance, AR/VR and responsive art direction. With Marcy Sutton, Yoav Weiss, Lyza D. Gardner, Laura Elizabeth and many others .

How To Approach The Writing

A carefully crafted requirements document eliminates ambiguity, thus ensuring that the developer does exactly what needs to be done. In addition, the document gives a clear picture of the scope of the work, enabling the developer to better assess the time and effort required. But how do we create a good document? Below are some tips that our mobile team at Polecat follows when crafting requirements.

1. Describe the Idea in General

We believe that a proper description of the idea should fit in one sentence. The sentence may include a core feature of the application, so that the reader understands instantly what the app is about. For a calorie-tracking mobile application, it could be, “An app to track calorie consumption to help those who care about their weight.”

Hint: Gua Tabidze shares a few models that others use to describe an idea.

2. Consider the Sequence

Study basic navigation patterns , and describe your application in the same sequence that users would experience while exploring it. Once the idea part is done, describe the first steps of the application, such as the onboarding screens and user registration.

Then, move on to what goes next, such as the application’s home screen. This approach will give the reader a sense of what the user’s journey would look like.

At the end, don’t forget about basic features and screens such as the privacy policy and the “forgot password” feature.

3. Review Existing Applications in the Stores

Review existing applications in Apple’s App Store and Google Play, and refer to them when describing your app. If you like how the “forgot password” feature works in applications A and B, put it in the requirements document.

4. Abstract Away From Detail

Focus on the features of the application, and skip details such as the color of a button. Most app users do not care about such details. What they do care about is whether your application helps to solve their problem. So, when writing requirements, concentrate on things that the user should be able to do in the app.

5. Prioritize Features

Convey which features are more important than others, so that the developer knows what to focus on first. We usually follow the MoSCoW method , marking items with “Must,” “Should,” “Could” and “Won’t” levels of priority.

6. Complement Text With Wireframes

Create wireframes of the screens of the application to accompany your textual description of them. If you have more than four wireframe screens, then drawing a screen map makes sense. We’ll show a screen map later in this article.

Requirements Formats

Now that you know how to write the requirements, you’ll need to choose an appropriate format for the document. There are a few basic formats for writing the requirements for a mobile app, such as a functional specification document (FSD), user stories and wireframes.

Functional Specification Document

An FSD is probably the default format in the software development industry. It consists of a standard list of items that cover what the product should do and how it should do it.

Let’s take a simple calculator application and describe its features as an FSD:

  • Application screen presents a digital keyboard with additional buttons for basic arithmetic operations (addition, subtraction, multiplication, division) and a result button (marked with “=”).
  • Tapping on a digit button adds it to the display section of the screen. Each new digit is added to the right side of the number.
  • Tapping on an operation button causes the current number shown in the display section to be added to the memory. It also clears the display section for the next number.
  • Tapping on the display-result button combines the number in memory with the one in the display section according to the operation requested previously. The resulting number is shown in the display section of the screen.

As you can see, this format requires quite a detailed description of the product because the description will be used by both the business and the developers. It ensures that all participants are on the same page.

The person who composes the FSD should have strong experience in software development and should know the specifics of the mobile or other platform for which you are building. Also, because of the high level of detail required, creating and polishing such a document usually takes a decent amount of time.

User Stories

A user story is less formal than an FSD yet still very powerful. It lists the things that the user can do in the application and is described from the user’s perspective. The document could also briefly explain why the user would want to do it, if that’s not obvious.

Let’s take our calculator example and add a few other features, describing them as a user story:

  • As a user, I want to be able to change the number notation from decimal to exponential (and vice versa), so that I can work with very small or very large numbers.
  • As a user, I want to be able to export a calculation’s history as a PDF file to share with my colleagues.

Because of the explanation, such a format provides not only a technical overview of the requirements, but also a good business case for them. Thus, if a feature is identified that is not critical to the business, you could decide either to completely remove it from the scope or to postpone it to a future release.

Using this format, you can easily split one story into multiple sub-stories to provide more detail. For example, we could split the PDF-exporting story into the following sub-stories:

  • As a user, I want to be able to tap on the sharing button (top right of the screen) to see my options (sharing as PDF, text, image).
  • Once I select a sharing option, I want to select the calculation timeframe that will be shared, using iOS’ date picker .

Because of the simplicity and non-technical nature of user stories, in most cases, a manager cannot simply ask a developer to implement a particular user story. Turning a story into a task that can be added to a task tracker requires further discussion and detailing between the manager and technical leader.

User stories have become one of the most convenient and popular formats because of their simplicity and flexibility.

Sketches and Wireframes

Another way to outline an application’s requirements is to visualize them in sketches or wireframes. With iOS development, around 70% of development time is spent on interface implementation, so having all of the screens in front of you would give you a good sense of what needs to be done and the scope of the work.

Calculator wireframe example
Calculator wireframe example created in Balsamiq Mockups .

Creating a relevant set of wireframes for a mobile application requires you to know the basics of the user experience: how screens can be linked with each other, which states each screen can have, and how the application will behave when it is opened from a push notification.

Mixing Formats

Don’t be afraid to mix formats. By doing this properly, you take advantage of the strengths of each format. In our experience, mixing user stories and wireframes makes the most sense. While the user stories describe the features of the application and provide a business case for them, the wireframes show how these features would appear on the screens of the app. In addition, putting together user stories and wireframes would take you less time than writing an FSD, with all of its accompanying detail and descriptions of the interactions.

Start by sketching out wireframes for the application. Once the wireframes are done, add two or more user stories for each screen, describing what the user can do on that screen. We’ve found this approach to be the most appropriate for mobile application development, so we use it a lot.

Let’s Practice

I’ll take our What I Eat application as an example. I’ll compose the requirements document as if we were developing the application from scratch.

First, let’s formalize the idea using Steve Blank’s XYZ pattern: “We help X do Y by doing Z.” The premise of the application is to enable users to take control of what they eat during the day and of their calorie intake. According to the XYZ method: “What I Eat helps those who care about their weight to track calorie consumption by providing functionality for a simple meal log.”

As mentioned, mixing user stories and wireframes works best for us, so why not use them here?

The next step is to describe the What I Eat app as user stories, screen by screen. We’ll begin with the application’s start and home screen:

  • As a user, I want to open the app and instantly see today’s meal log and the calories consumed.
  • I want to be able to quickly add new meals and calories that I’ve just consumed.
  • I also want quick access to the in-app calendar to view my meal logs from previous days.

To avoid any ambiguity, we’ll create a wireframe for this screen.

Home screen wireframe
Home screen wireframe

As you can see, we weren’t able to put the “Add new meal” functionality on the home screen. Instead, we added a button to navigate to another screen that presents this feature. Now, we need to put together user stories for this new screen:

  • I want to type in the name of the meal I’ve just had.
  • Along with the name of the meal, I want to enter the number of calories.

Wireframe for add meal screen
Wireframe for add-meal screen

The home screen has a button that opens the calendar. Because there are many other calendar apps, checking their designs first makes sense. We like the iPhone’s default calendar app, so we will use it as a reference.

  • As a user, I want to be able to quickly select a date in the current month.
  • When selecting a date, I want to see a list of meals for that date below, like in the iPhone’s calendar app.
  • I want to be able to switch to the next or previous month.

We will also put a piece of the iPhone calendar’s user interface in the wireframe.

Calendar wireframe
Calendar wireframe

Finally, we need to add some settings to the app.

  • I want to be able to enable and disable iCloud backups for my meal records.
  • I want to be able to enable and disable daily push notifications that remind me to track my calorie intake.

Wireframe of settings screen
Wireframe of settings screen

Phew! Almost done. The final step is to put the wireframes and user stories together in one document, with each wireframe and its respective story on its own page.

Wireframe and user stories
Wireframe and respective user story on one page. Download the full document (PDF, 0.2 MB). ( View large version )

In addition, we can draw a map to visualize how the screens are connected to each other. We’ll use RealtimeBoard for that.

Screen map for calorie-tracking iPhone application
Screen map for calorie-tracking iPhone application ( View large version )

In doing the screen map, we realize that there is no button to go to the settings screen, so we’ll add that to the home screen.


We have created two documents: a PDF with user stories and wireframes, and a screen map that complements the PDF. Together, they describe in detail what features the application should have. We can go ahead and send that to our developer. This time, the application he delivers will correlate with your vision.

Generally speaking, writing a requirements document is mostly about conveying your vision to the rest of the team. Don’t limit yourself to the methodology described above. Feel free to experiment and find the solution that works best for you.


Delve deeper into the subject with the following resources:

  • Story Splitting Cheat Sheet (PDF, 0.25 MB)
  • 10 Tips for Writing Good User Stories , Roman Pichler
  • The Wireframe Perfectionist’s Guide , Edric Lapniramai, Smashing Magazine
  • Designing Features Using Job Stories , Alan Klement, Intercom

We’d love to hear about your approach to creating requirements documents. Please share your thoughts in the comments.

Smashing Editorial
(da, vf, yk, al, il)