A Prototype is Nothing More Than a Picture


Sure, you put a lot of time into creating a prototype, a mockup, screenshot, or wireframe (are there any other names for the user interface drawing I’ve missed?). You may have drawn it on a whiteboard, in VISIO, or even used a requirements tool to create it. At the end of the day, no matter how much time you spend on it, it’s nothing more than a picture. And those of you who have worked in IT know developers cannot code and create a solution solely from a picture.

So that developers can code the solution and create the expected functionality, you need to create the accompanying description for the prototype. This could be called a user interface specification, or prototype functional description, or some other document. No matter what you name it (I’ll call it the User Interface Specification, or UI Spec), it’s the piece of information that explains in detail how the user interfaces with the software, and it sets up the expectations for the behavior of the system.

                         A Prototype is Nothing More Than a Picture

Take for example, the mockup of the screen design for the flight reservation system. If this were the only artifact handed over to a developer, how would a developer code it? You may respond:

• he knows which objects to put on the screen
• he knows where to place them
• how the user interacts with the screen is his guess

What that guess leads to is different functionality at best, to missed functionality at worst. So how do we overcome the guesses developers will make to ensure the solution is what the business expects? EXACTLY – we create the User Interface Specification.

The User Interface Specification explains in depth everything contained on the prototype of the screen; each label, control, and interaction the user will experience. There are 2 parts to the UI spec:

  • Field descriptions, containing the labels and graphics and their sources and types

  • Screen Controls, describing the expected way in which the system functions in response to the user input and interaction.

The combination of the 2 of these explain the prototype (the picture) in depth to both the business user (to make sure it meets the business’ expectation) and to the implementation SME (or developer) so he will know what is needed when crafting the software solution. I prefer to show them as 2 tables following the graphic. These are the Field Descriptions and Screen Controls.

The field descriptions explain the labels and other screen items the users cannot interact with. They are generally static, but could contain data pulled in from parts of the system. For instance, the screen could say, “Welcome, Paul” and you would document that as shown in the Field Descriptions example. Note how in the third row of the table below, it explains how subsequent tabs would be displayed in the Flight Reservation System. They will only be displayed after the user completes this particular tab. And since this tab is all about the search, you’d have to explain how the search results are displayed, on the Search tab or the confirm tab. All of the expectations for how you want the system to perform need to be documented. If you are heavily into different UI functions, you can argue that proceeding to other parts of the system could also be a status bar, or breadcrumb, but in this fictional example, it was a tab.

Field Descriptions

Name Type Source Description Field Length Defaults Req/ Opt
Welcome, Paul Dynamic Label User Profile Displays the welcome message along with the first name of the logged-in user. If no user is logged in, displays “Guest” n/a “Welcome, [FirstName]” n/a
Flight Reservation System Label System Displays the label on the title bar. n/a n/a n/a
Step 1: Search Tab System System displays the tab showing where the user is within the process. Users cannot navigate to subsequent tabs until this screen is completed n/a This is the 1st tab the system displays n/a

Screen Controls are those widgets on the screen the users interact with. You may have had many conversations with the business during functional design about how these would operate, but if those conversations were not documented, the functionality can be quickly lost when it goes in front of the developer to code. If you look at the Flight Reservation System, the first interactive control is a Round Trip/One Way exclusive selection. They are linked with radio buttons in this screen shot – this is a control that is an exclusive control – when one is on, the other is off. The implementation SME may code it slightly different (and show different controls) but must adhere to the functionality. Notice how rows one and two show this functionality and how they affect each other.

Screen Controls

Name Control Type Function Description Enable/ Disable Conditions
Round Trip Exclusive Selection When selected, it turns off the focus from the One Way radio button. Selecting this control also enables the Return date control. Always Enabled
One Way Exclusive Selection When selected, it turns off the focus from the Round Trip radio button and disables and greys-out the Return date control. Always Enabled
From Text entry System will start to find matching airports after the users enter the first 3 characters, and display those matching the selection in a list below the text box. Airports can be searched by typing in the IATA code (ATL), city (Atlanta), or airport name (Hartsfield-Jackson). The users can highlight one of the found selections and choose it. Doing so will populate the city and airport name into the text box in the format “City (airport name)” Always Enabled
Include Nearby Airport Check box When checked, it will include search results for airports providing service within 30 miles distance from the selected airport. Always Enabled
Return Date Becomes enabled if a round-trip flight is chosen and only becomes active once the Depart date is chosen. The Return bases its first date to return as the same day as that chosen in Depart. All dates after the Depart date are active. Disabled when One Way is selected
Find Flights Action Enabler Control only becomes enabled when users have indicated a From and To airport, a From date (and a To date if Round-Trip was selected), and at least 1 Adult or 1 Child selected. Executing the control (by clicking or tapping) starts the search process with the selected parameters on this screen. Enabled when search selections (as detailed) are made
Class Selection Defined selection for flights. Defaults to “Economy”. Selections available include “1st Class, Business, Economy Comfort, and Economy” Always enabled

While to those of us who do screen design, this might seem obvious functionality. But if not documented, some things might be missed. Look at the description of how the From text box operates. Do you think developer would have coded it that way without having directions on how to do it? You are most likely thinking, “Probably not” and you would be correct. They may get it right if they were involved in the functional discussions, and even then, they would have had to remember it when they went back to their desks.

Notice how when the UI spec is detailed out, errors can be averted. In the case of the Return date, it shows how the control becomes enabled or disabled (when the one-way option is chosen), or even how the dates available for selection become dependent on a separate control, and the information on that control. Developers can then see how they need to be reading the data and verifying all information is completed on the screen in order to process events. In the control for Class, you can see how the values users are able to choose are displayed. Note that it doesn’t get into a lot of detail about how all of the different fare classes map to the values in the list – that mapping would be contained in the data dictionary. This just shows the functionality and what is expected when it occurs.

No matter how you choose to explain the detailed functionality behind the user interface, you still have to document it. It becomes even more crucial as virtual workspaces become more prevalent in today’s work world. When people aren’t co-located and available to talk through the functionality, it has to be documented so everyone arrives on the same page when the system is developed.

How do you successfully document the functionality contained in the prototype?

Author: Paul Mulvey is a sought-after business analyst, speaker, author, business advisor, and BA-instructor. He most recently authored the book Business Analysis for Dummies during his tenure at B2T Training. He has developed BA Centers of Excellence, rolled out custom-developed software and packaged software, and has managed teams of BAs in various organizations. He finds his passion is getting people to understand business analysis is more than just a title.

Like this article:
  35 members liked this article


Karl Wiegers posted on Wednesday, July 10, 2013 5:32 PM
A really valuable supplement to the detailed information about screen fields and controls is a "dialog map", a visual representation of the navigation options that users have to move from one dialog element (screen, menu, workspace, webpage, dialog box, line prompt, etc.) to another. The field and control specifications described in this article represent detailed design of the UI, whereas the dialog map represents the UI architecture. The dialog map is nothing more than a state-transition diagram: boxes and arrows.

Dialog maps capture the essence of the user–system interactions and task flow without getting bogged down prematurely in detailed screen layouts. Users can trace through a dialog map to find missing, incorrect, or unnecessary transitions, and hence missing, incorrect, or unnecessary requirements. They're also very valuable for testing.

Dialog maps are described in Chapter 12 of my book "Software Requirements, 2nd Edition". The third edition, co-authored with Joy Beatty, will be published August 22, 2013.
Mick Wren posted on Thursday, July 11, 2013 6:44 AM
Paul, I suspect that you are being intentionally contentious with this article. I would question whether anyone who hands over a picture and expects it to be developed should be in an analyst's role.

There are many types of prototypes of course, some of which don't need any UI, but taking your example I would provide even more detail than you show in your example. I'd explain the background to and objectives of the prototype. I'd also provide a description of the processing logic (typically using process flows with descriptions) and also an underlying data model. Usually, I also provide one or more worked examples and even some test data and expected results.

All of the above of course depends on the objectives of creating the prototype.
Putcha posted on Saturday, July 13, 2013 2:00 PM

I find this article extremely helpful and necessary to a BA and RE, who normally leave out many of the essential details of "UI Specification" mistaking it to be "UI Design" which technically and rightly is not within the scope of a Business Requirement Document"

However, calling a "prototype" a "picture" is a deliberate and misleading understatement. A prototype is a "functional" in some manner however coarse and minimal it is. Even then, it is a "lot more than a picture" however detailed and vivid it may be. Still I accept it as "emphasis" of the need to supplement a prototype with VITAL information.

The tables serve as simple and excellent framework to remind a BA and RE and also developers on what all are needed to be added before design. One may say it crosses the border between analysis and design but it is still better use the tables omitting such details which may belong to design.

The comments by Karl Wiegers whom I know to be an authority on the subject are apt and worth noting and using. Karl's Dialog Maps fill the gaping gap between Use Case Diagram and Use Case Descriptions. Paul's Tables (find some apt names for them, Paul) lend precision, meaning and "realizability" to description of functionality.

Mick Wren seems to be another accomplished expert (sorry for not knowing you earlier Mick) whose advice is illuminating IMO without subtracting anything written by Paul.

Paul, I do not recall seeing you on LinkedIn. Many groups there can benefit from what you say with some arguments of course.


[email protected]
Karl Wiegers posted on Saturday, July 13, 2013 2:36 PM
@putchavn: Actually, there *are* names and established notations for the kinds of tables that Paul showed for field descriptions and screen controls. In the book "Visual Models for Software Requirements" (Microsoft Press 2012), Joy Beatty and Anthony Chen describe a Display-Action-Response model for providing detailed UI specifications, going far beyond what a prototype will illustrate. Field descriptions often are found in a data dictionary.

I recommend using established notations and models in general, inventing a new method only when you've found that all existing methods are inadequate for your situation, or enhancing existing models to build a better mousetrap based on experience.... Karl Wiegers
Putcha posted on Saturday, July 13, 2013 5:00 PM

Thanks for the information. I did not see any references in BA and RE literature (of course I have not exhaustively covered all publications). Even your Dialog Maps or Scott Amber's “User Interface Flow Diagrams (Storyboards)" also called "Navigation Diagrams" by Scott W Ambler's “User Interface Flow Diagrams (Storyboards)" also called "Navigation Diagrams" are not well known in spite of the vital gap they fill.

Yes, I am aware of field descriptions in data dictionary but I thought they are not in use in OOAD / UML.

Paul Mulvey posted on Friday, August 16, 2013 9:42 AM
@mick - the title was intentionally contentious (trying to drive people to read it by wondering what I meant). The purpose was to show how drawing a picture or creating a mockup of a screenshot needs a lot more information behind it. This sets up the expectation for what will be developed and what the users or stakeholders will get in the end. And true, in agile, you may be developing the detail side-by-side in the code with the product owner, so you may not have all this documented detail, but you still have to know how you expect the "picture" to function (but I think you know this).

@Karl - I saw Joy present her concepts at a conference (I think it was WI-BADD?) and was tweeting during the preso because it was similar to what I have developed and "preached" to other BAs. I will look into your dialog maps you discussed. Could be a way to establish a quicker way to get to the detail.

@putchavn - you can find me on linkedin at www.linkedin.com/in/paulmulvey. Would love to connect!
Only registered users may post comments.


Upcoming Live Webinars


Copyright 2006-2024 by Modern Analyst Media LLC