Writing App Requirements for Your Programmer

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.

Example:

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.

7 Replies to “Writing App Requirements for Your Programmer”

  1. These are very helpful suggestions for communicating with programmers. I’m also interested to know how you pre-arrange for changes in the application that will surely become a part of the development process when coming to an agreement with programmer.

  2. Hi Mathew – Good Question…and a tricky one. I think this really depends on the relationship you have with your programmer teammates. If it is a new engagement, I would insist on a brief Statement of Work that accounts for you, as the purchaser of services, having the need for requirements completed to spec during the development process. So said another way…if it doesn’t work as expected, your programmer will continue to work until it is right.

    Your requirements document is your guarantee in this regard. If your specs are clear and as literal as possible (they might even read painfully obvious to you), they act as your leverage if the development of the app is unsatisfactory (i.e., you go back to section X in your document and say “it says this and you developed this, need it fixed…”).

    So prior to selecting your programmer, I would have your specs polished. That way your coder knows what he is signing up for….and guaranteeing to deliver when he signs the Statement of work. Hope that is helpful.

  3. Wonderful article. I think prototyping is the best way to flushout requirements no matter what app/software it is. I always show the users what they are going to get in a prototype so there is no surprises when they get final product or bill 🙂

  4. This is a well-done article, thank you! I would add one suggestion to the early part of it: All too often, interactions with developers go to a conversation about features that an app should have. Having built many apps and led development teams for years, I have found that it is very important for your development team to hear what the intended experience of the user should be, how you want them to be engaged, what they should enjoy and why, and how/why they would come back to the game. For example: take the text narrative above, which is nicely done, and remove all references to features like the Animal Wheel, the specific song, the specifics of how the matching works – you get a short description of an app that engages children by using their favorite (and other) animals, familiar songs, to play with and identify shapes, and to receive simple rewards in the form of music.

    By simplifying the essential story of the app to the user experience (without getting into features), you will be able to narrow the development effort to the initial, essential scope (i.e., make it less expensive), and you’ll see quickly whether your scope is sufficient to engage the user long enough (i.e., ensure your app has a shot at success).

  5. This is a very helpful article certainly. It is providing a guide for me to put together a more detailed document to search for a developer. Here is my only question though, during the selection process when I have different developers sign an NDA with me, so that I am able to share the requirements document with them, should my requirements document include all the details i.e detailed screen descriptions ?

Leave a Reply

Your email address will not be published. Required fields are marked *