A long, long time ago while working on a web-based product, a colleague of mine came up with this idea of writing a user interface or screen specification. The purpose of this requirements specification is to detail out the rules behind a specific page. Sure, this type of document can become “implementation” than “requirements” but the fact is when you are building a complex software application (and that includes web-based applications) the way a specific page is laid out and, just as important, what data elements belong where, is very important.
Why Specify User Interface Requirements?
Think about the home page of your company’s website or your LinkedIn home page. Complex pages that display massive amounts of information in intelligible ways don’t just create themselves. They are products of intentional design and careful analysis.
- As a BA, do you tend to leave these “design” elements to your development team to flesh out?
- How much churn is that creating during implementation?
- Would you be interested in exploring a better way to capture these rules, without over-stepping your role as a business analyst?
Elements of a User Interface Specification Template
AÂ UI specification defines the rules of engagement for a user interacting with a specific page on a website or screen within an application. A UI specification can have the following elements, take or leave a few depending on the situation:
- Visual overview of the screen. Break the screen up into sections. This will help organize your document. You can do this in Word with a few text boxes. Label each section and include a “section” in your document for it.
- Within each section, look for the display rules. For example, on a search results page, how are items sorted? What fields are displayed? What if a particular field is missing?
- Consider messaging. Do you want to display specific messages in specific conditions? If so, what are they?
- Evaluate the links. Is it obvious what pages each link should be directed to? If not, specify it.
Good UI specifications take into account the data and context of the user within the application. This sort of requirement specification does not replace UI design, but it does help you lead your team through thinking through the UI design and how users will actually experience information within it.
Fitting the UI Specification Into Your Requirements Model
There’s an obvious blend here between functional requirements and non-functional ones. Sometimes a few functionality requirements make their way into your screen specs. I try not to worry about this to much. But if you find yourself writing out a bunch of “if then” statements, then you are probably trying to use a UI specification to substitute for a use case or other functional spec, and you might consider breaking it out and simply “calling” that use case within the screen spec.
And on a final note, not every screen needs a UI specification, only the more complex screens. The intent is to reduce ambiguity and drive alignment around complex rules. For a simple screen with a few rules, these rules might be best captured in the special requirements section of a use case or in a separate business rules document.
>>Don’t Start From Scratch
If you’d like to create these types of user interface specifications on your next project, I’ve made an fully annotated version of my UI specification template available (along with a host of other useful and practical templates) in the Business Analyst Template Toolkit. The toolkit includes 11 additional templates covering common BA documents, each accompanied with a work sample too.
I a beginner in ui design standard how and where to start designing what is the rules of this type designing please help me give me some examples
thanks
Mohd Javed
Hi Mohd,
You might want to check out the BA Template Toolkit as it has an annotated template for creating a UI Spec per the structure in this blog post: https://www.bridging-the-gap.com/business-analyst-template-toolkit/
Dear Laura,
Very nice article. You have formalized UI spec quite well. We used this approach in one of our project which was about migrating a legacy application to Java. This application was very UI intensive ( CRUD being the most basic functionality all screen had..) . The most complex screens called lot of other screen (read-only,search or other sub screen with CRUD)..
It would be nice to have a UI map in the beginning as an overview for such complex screen..and then follow that with detailing each screen is chapters..
Also it very easy to put all properties for each screen components like type,format,description etc in tables followed by validation rules for each components ..the validation rules display the messages where applicable..
“Break the rules”
>> makes sense 🙂
Whoever thought people could become BA’s by reading BABOK or understanding UML …
BA is a mental discipline that is achieved through hardwork and long times of painful organization and re-orgazination of ideas and representations of those ideas. It’s the most demanding of all jobs.
Hello ,
Recently i am put on healthcare project for hospitals. BRD and FSD is ready. I am told to create User interfaces based on functional specs. I dont have any idea of doing this. As a BS this is my first assignments. Help me how to start with and can i do in powerpoint.
Regards,
Alekya
Aleka
1 is this a new system or existing
2. Is this web, vb, sap or a hospital consol in cobol? What type of app is it
3. What is the difference in ur BRD and FSD?
Hi Alekya,
Thanks for stopping by and good luck with your project. Your question is a complex one and a lot depends on the questions Kai asks but also what the use for the specs will be, etc. Is there someone in your organization you can ask for some assistance in establishing expectations and working through this first project? If not, you might check out our mentoring program as we’ll be able to pair you up with a senior BA who could help you out over the phone.
https://www.bridging-the-gap.com/business-analyst-career-mentor/
Best,
Laura
Going through the mockups is fine. I would suggest a “dynamic” walkthrough where you “play computer” while an assistant, or less ideally a representative of the customer, uses a pointer to click through the set of mockups. You then expose the next screen, or shift focus to the new area of the same screen. You can also give them the feedback that would be experienced if they don’t provide the required input, etc. With a proper introduction, explaining how your are going to present the mockups, your audience should appreciate your efforts and allow that your aren’t as fast as a computer, and may fumble around a bit finding the next mockup. You do need a comprehensive understanding of the whole setup (and lots of practice). I would suggest writing up and index to help you navigate. Also keep a pad handy to take notes on where there were issues that were not demo related. These notes should include spoken comments as well as hesitations or confusion you notice, again excluding those that were caused by the nature of the demonstration. There is a usablity technique called “thinking aloud” where the participant describes what he or she is thinking, which will help you understand when difficulties arise. It often requires you to prompt them when there is a long silence, but it provides insights you would miss otherwise. You can also record them for later transcription if that is helpful, and particularly if you are doing this alone.
Does this make sense in your situation? I have done this, and seen it done, several times. The viewers always liked the ability to play with / explore the interface this way. It can also be a good first usability test, that will yield a better product in the end.
Good luck, Jim.
Hi Jim,
I have a walkthrough with the customer next week. I am trying to see how how i want to run the meeting to best shows the look at behavior. I have a BRD done and I have screen mockups done. I was going to go through the mockups one at a time to show the look but then it would not convey the behavior? Any sugguestions on how to facilitate a meeting using low-level prototypes?
thanks Jim
kai,
Interface and UI (user interface) are usually the same, although there can be program interfaces too (called API for Application Program Interface). A prototype is usually a simplified implementation of the UI. One flavor of the prototype is often called an executable prototype, which means it will eventually become the actual UI. The other flavor is a model prototype, which is used to specify the interface, but is never (well, hardly ever) expected to appear in an actual product. Included in the latter are “low fidelity” prototypes, which can be drawn on a whiteboard or paper, and the users can be walked through, simulating the expected UI behavior. You can also produce low fidelity prototypes in Visio or with protptyping tools. The better they look, the more likely your users will choose not to change them, because they look hard to change.
and
Two possible items spring to mind: the navigation within and among the pages, and the business rules associated with the application. Among these rules are what are valid values for a given field, and what behavior is exhibited when there are errors (or simple exceptions, and what constitutes these excpetions). One exampel of this is how the system behaves when it is presented with multiple invalid values. Does it prompt for corrections one by one, or does it present all the invalid fields at once.
Best of luck, Jim.
Today I saw
1. a requirement with a “prototype” section in the appendix.
2. a Implementation document that pretty much was the Screen shots, the fields, database names, store procs
So It has me wondering what is the difference in the terms UI, interface and prototype.
and
If you are working on a requirment for a webpage and your ui spec has everything in it pertaiing to the webpage then what is left to write in the business requirment?
thanks
Just got assigned a new project..i completly understand the project but now need to paint the picture:) This project is to incorporate new features into an existing company webpage that another team developed. They said I need to provide a wireframe and requirment plus work with deveopers for a sequence diagram. then we will have a meeting to do a mapping/label type of exercise to pass the data into the templates or something like that. Still undersure what all that entails but i know i want to have my wireframe/requirment he is requesting done by tomorrow. Any tips on how to start or do a web requirment and wireframe? I am not really confident in what they other team is asking for?
RE. test cases: It depends. Some shops have the BA do test cases, others have dedicated QA staff who work with the BA and develop test cases. Although usually quite detailed, the test cases need not be elaborate. Test scripts are more so. The object of a test case is to test the execution of a use case (or similar level requirement).
Ok I am not sure which developer i will be assigned but i spoke to one who is familiar with the app and he said a textual requirement was sufficient..so…I guess I was trying to do over kill.
PS…Do Business analyst do test cases for their unit test? I see there are lots of BA’s who do this elaborate test case documents and I am like EKKK!
kai,
As Laura suggests, check with your developers to be sure they can consume (effectively) what you are providing. Then you have got it.
The organization of the material is just the same. Some developers prefer the material intermixed, some prefer them in rigid categories. Yours will be happy to tell you what they prefer. The Axure model can be part of a Word document or standalone executable HTML, although the document allows for more annotation, which is usually a good thing.
Good luck, Jim.
OHHH got it! I will keep the text of the requirement. Below it I will take a pic of the screen Make edits using ?? I have snagit not sure it it lets me do arrows and text will play with it.
2. Use a use case to show the interaction
3. Use a UI flow diagram IF i need to model the flow btw forms.
Is there something wrong with having all this in the area of the requirment or is it best to place the usecase and UI diagram in the appendix?
I think I got it 🙂
Kai,
You asked “How do you know if a textual Requirment is sufficent or if I need to model it?”
You are on the right track by considering the perspective of your developers in your decision. Have you asked them what would work best for them or make their work the easiest?
If they don’t know you might experiment with a few different approaches for subsets of your requirements and review them with your developers to see what works best. There is no one right answer to your question, just many options.
And Jim is right, Axure will work for most of your UI modeling needs. Balsamiq would also work but require more overhead in terms of the time to create and modify the pages.
And as you are specifying these small changes, don’t forget to look for the potential impacts. A new field on one screen may impact others or impact reports, etc. Often it’s these deceptively simple requirements that cause us the most pain!
No, but a use case can describe the information that is transferred (both ways), and interactions between a person and the system. That’s why I called it a supplement. The layout and fields are in the screenshot.
Hmm i dont think in a usecase I can show the fields that are to be read only, prepopulated or a new button?
kai,
If I can make a few suggestions, don’t do both an old screen shot and a new wireframe (for which Axure works well). An old screen shot with markups has worked well for me in the past. It is much easier to do (therefore with less investment, and easier / cheaper to change).
Activity diagrams sometimes help, but cannot carry the load of a visual design.
Consider supplementing the screen shot with a use case (in the UML or RUP sense) that describes what the user expects to accomplish. You can then test the UI by walking through the use case.
I have a bunch of changes to an exisitng system that the user would like changed. Some are added text boxes, removed drop down boxes or change in the response on the click of a button or slection in a dropdown.
How do you know if a textual Requirment is sufficent or if I need to model it?
My goal is to identify the best method for my developers to look at my requirment, implement the changes to the screen and the responses without having to read through a lot of text and having to map out in his mind what to do.
I was thinking I could
1. Create “old screen shot” with notations of Remove this, add this, Onclick do that?
or
2. Create a new screen shot-Not sure what software i could use to add some boxes etc to the screen
0r
3. a UI type activity diagram to show onclick, if this then that type of flow from screen to screen
or
4. A table that shows maybe
Screen name Action System Response
or
a combination of any of these
I dont want to make it cumbersome because some of these are minor screen changes just needing direct as to how i know when i need to do more than write the requirment and what will be the best method to get the point across when having a
1. Screen Edit and/or
2. Behavior response.
Hi Gerald,
Typically those types of questions are geared toward your subjective opinion of a specific user interface? Do you like the colors, design? Is it intuitive to use? Etc.
Jim, Yes it’s definitely a gray area, no doubt about it. But it is a very useful tool in terms of ensuring your requirements are translated into the appropriate designs.
Eric, interesting break-down of roles. Typically when I’ve worked with a UI team or designer, a lot of this responsibility ends up in their court. I might do some early mock-ups to validate the requirements and then circle back with the UI design team to ensure the appropriate business rules / logic are incorporated into the design.
Laura
I once had a person ask me which UI I liked best… I didnt understand what he ment by that. Do you?
Interesting article! We have actually implemented some tools and techniques within our BA team (working in a great web consulting company) to integrate use cases to wireframes & prototypes (made using Axure). For more complex websites (e-commerce) and web applications, it leads to interesting results.
As for who should handle this wireframing task, I think that BAs are well positionned to capture client needs and prototype them. We work closely with the UX/design team for their feedback, but the BA is in charge of creating the UI (and the specs required to document business rules).
Pingback: How to create a user interface specifica… « Ask Software Specifications
I like your idea of a UI spec “calling” a use case. For me the user interface is a gray area shared between requirements and design. My preference is to leave design to designers and requirements to analysts, but in practice both must contribute for an application to be to successful. A good BA has at least some sense of what the user experience should be.
Hi Laura
I just found your blog and the entry on UI specification. Maybe you like to visit my blog, too. We could share some thoughts as I already wrote several papers on UI specification practice and the according tools.
Thomas
Thanks for your comments, Harris. I defer the claim to expertise if for no other reason that it allows me to put some tentative ideas out there without having to be “right”! 🙂
But I do agree that thinking through the rules around how the UI flows drives usability (or it’s converse), whether you bring formal UX expertise to the activity or not.
Laura
Hi Maureen, Thanks for your question. I have often used screen captures in use cases and I think that’s a great technique to capture the intent of the requirements when a full UI spec is not necessary. In cases where a use case references a screen detailed in a UI spec I put the screen capture in the UI spec instead and “extend” the use case to reference the UI spec (or just reference it at the right point in the flow).
Laura
Thanks for the insight to writing UI specs. I believe the BA should be giving direction to design.
How do you feel about including screen captures in the use case (as a reference)?
regards
Maureen
Laura,
I think you’re mistaken if you say you’re not a “usability” expert. Understanding the users motivation and mindset is the first step to usability and that sounds exactly like what you’re doing.
Building a simple set of core-metaphors for the system and facilitating a set of UI prototypes that reflect how they will use and interact with these metaphors means a lot more usability than the “fluffy” side.
Users engage with UI mock-ups more than any other sort of model – the fact that it’s not in UML or detailed in BABOK doesn’t really matter.
P.S. Balsamiq or Niklas Wolkerts Visio stencils that give things a hand drawn look to mockups are really fantastic – separate out the layout and interaction design from the graphic design portions.
http://www.guuui.com/issues/02_07.php
http://www.balsamiq.com/
Hi Jeremy,
Thanks for your comment. It provides an interesting characterization of the roles. In your experience, does a UX professional provide these level of detail? I have to say, in my experience, the UX is left at a fairly high level and without something like a UI spec that integrates the intended experience on the front-end with the information model on the back-end and all of it married with the multiple possible paths the user can take through the system, the user experience is not truly realized in the final application.
Cheers,
Laura
P.S. I see how my words could be read to infer that UX = graphic design. Just want to let all you UX-ers out there I was referring to two components of the user interface, neither of which I have any claim to expertise in doing, only facilitating.
This will hopefully sound obvious if it is not something you are consciously aware of, but the value of software is derived through the experience. The best requirements and the cleanest code sitting behind a poor user experience will result in a failed product.
It’s good that you are stepping up to do this work. It is extremely helpful and will point out issues that can be resolved conceptually long before extensive code is written. Wireframes are often the first activity that I will introduce to an organization new to user experience as significant benefit and time savings are quickly realized.
However, realize that you are doing much more than just dabbling in user experience, by authoring this document, you are defining it, whether or not you have formal training or extensive experience as a practitioner of User Experience. Whether it is a designer, BA, or engineer, someone will ‘design’ the user experience. The more skill that person has, the more effective that activity will be.
The fact that you relegate UX to graphic design demonstrates that you have not had the pleasure of working with an experienced Information Architect, Interaction Designer, Content Strategist, or User Researcher. There is much more to creating a positive experience than the visual treatment. It’s good that you call out that this exercise is not a replacement for proper user experience work.
As an aside, UX work doesn’t have to take months, see Jeff Patton for integrating UX and agile.
http://agileproductdesign.com/blog/
Good luck. There are lots of resources, both educational and talent, that can help your projects progress and succeed.
Great point, Mark. I typically don’t start with these documents, but do start with dynamic, click-through wire-frames to get user feedback.
A good start, but for better way see use of Visualization, which takes it from static to dynamic
Thanks, Kevin. I suppose I should dig a bit deeper into my BABOK before making such comments. I see the UI spec as separate from the prototype, which I often do as well, and focusing on the rules behind the screens, not so much the layout and look-and-feel that a prototype presents.
In my experience UI designers focus more on the look and less on the rules. There is often analysis involved in ensuring the screens are implementable against the information model.
Laura,
If it makes you feel better, it actually IS in the BABOK under the Prototyping technique (a UI spec is essentially a paper prototype).
We didn’t spend a lot of time on it because UI specs really fall into the user experience area, and like product management, that’s something that has a lot of stuff in common with business analysis while being different enough that it’s difficult to address it intelligently in the same standard. However, if you look closely at how we define requirement, a UI spec can definitely qualify.