Writing App Requirements for Your Programmer

by Moms With Apps on September 4, 2011

Our feature this week is written by Wendy Watts of LoeschWare, creators of five kid-friendly apps on the App Store. Wendy outlines internal processes for writing app requirements for their programmers. This topic comes at a timely moment, because later this month MWA will be speaking at SheStreams on the topic of “Taking Your Brand Mobile”. The LoeschWare process will be in our arsenal of hints to share for new app developers. Thank you so much Wendy!

Below are several easy steps to follow for communicating the intent of your design to your team members that are responsible for coding your applications.  Whether you hire externally or do it as a family, being clear and concise always leads to better, cleaner product results.  Which of course, means more productivity for everyone.   We’ve listed several “steps” that we use as a team for creating coherence when writing our requirements:  1. A text narrative providing high-level app context,  2. A scope outline listing product features, 3. Detailed screen design, 4. A file inventory, and 5. Putting it all together in a readable and understandable workflow document.

1. Text Narrative:  Write up your app idea as a brief narrative.   This is a 2- minute summary that should capture the essence of what the application does with emphasis on the features of the game that best capture its intent.   You can also provide a component view (the primary blocks of stuff that need to be built) or provide a high level workflow to show the flow of the app a different way.


The Old MacDonald Game is a music and animal identification game that allows children to learn a variety of animals, both farm type animals and others that do not belong on a farm.  The game’s theme is the “Old Macdonald had a Farm” nursery song, which is a public domain song/nursery rhyme that dates back the early 1700’s. 

The “Old MacDonald” song frames the game and the end user completes the song verses by placing animals from the “Animal Wheel” menu into the correct place on the farm.  The end user is guided to place certain farm animals in designated spots by dragging the animals to matching “silhouettes”.   The game and its theme song advance when farm animals are dragged to their proper location after being selected from the animal wheel.   When the animal is placed in its proper location, the “Old MacDonald” song verse completes and the user is brought back to “Animal Wheel” menu above the farm.

Animals that do not belong on a farm are also available for selection.  These animals can be selected from the animal wheel, but instead of being available for placement on the farm, these animals will go to a default location in the front of the farm.  Old Macdonald’s tractor or his donkey will remove animals that do not belong on a farm. 

The game is completed when all farm animals have been placed on the farm correctly.  The end user is treated with an outro from Old MacDonald and the user has the option to restart the game for additional play.

Note that there are two primary scenes (See Screen Shot M).  The two scenes are: A) The Farm and B) The Animal Wheel.  The animal wheel resides in the sky and end user should transition to this scene smoothly as if a single large scene.  

2. Scope Outline:  This is your “scope” or what features will make up your app.   Your outline should show all the components of the app, logically arranged, that you need to provide requirements direction (how the app should look, feel, respond) in order to capture the intent of the design.   You want to try to finalize your scope at this point because this is how you will obtain your pricing from your programmers …..they need to know how much you are asking for so they can determine a level of effort and thus cost to bill you.    You should try to remain true to your original scope if you can help it; adding features and functionality along the way is the best way to kill your timelines and expand your costs.  It might also result in rework which quickly “takes the wind” out of your project’s sails.

3. Detailed Screen Design:  Once you’ve determined the high level features of your applications, it’s time to design the user experience.   A good way to think about this is “actions” and “responses”.   For example, the user fires up your app.  What do they see to invoke their own interaction with the app?  Select a “Get Started Button”?  Swipe down? Select an action?  Each action might produce a response on the current screen or take the end user down a new path entirely.  These new paths are “scenarios” and should tie back to the major scope items you identified in your outline.


4. Determine Your Graphic and Sound Files:  LoeschWare develops its own audio and graphic files.   So once we defined how we want the screens to look, feel, and sound (our design), it’s time for us to create our graphics and audio.   We first create an inventory of files we expect that we will need for the app.   From this point, we divide and conquer.  Once we have our files, we can then produce a document that our coders can read from start to finish to code the application.

5. Putting it all together….your Requirements Document:   You can now take your narratives, outline, design (actions and responses), and your files and combine them for a comprehensive guide for your coders to assemble the final product.  It should be easy to read, exhaustively thorough, and “living”.  By this we mean its creation is iterative; as you have discussions with your team, you will find tweaks in the design that necessitate that you update your Requirements Document.   Remember, you aren’t changing the scope (adding features), but clarifying the design given ongoing design conversations as well as best practices and coding constraints that your programmers might bring forward as they assemble the application.  As you can see in the example below, we make file references as we show the design and describe the action and responses of the application.

We’ve found the above steps to be an approach that we can repeat successfully.  Your approach may vary slightly or you may have your own documenting approach that you prefer.   Whichever way you go, one thing is clear:  Simplicity is king.   If your programmer teammates are asking a lot of questions after reading your documents, you probably have opportunities for improving your clarity and approach.

LoeschWare is a small business that ultimately grew from the process of raising families.  Technology is inevitably part of our lives; our children are drawn to it.   We’ve simply taken what we believe is a fun and natural way of interacting with children, both typical and with special needs, and delivered this in a medium that is quickly becoming the computing and learning platforms of the future.   Our approach and philosophy makes our products more relevant because they are derived from proven teaching methods that engage children.  We know this because we are raising our kids in tandem with our educational titles.

{ 6 comments… read them below or add one }