How To Describe Software Features To Developers
Clients (business people) and programmers speak and think differently. Miscommunication leads to programmers not delivering what the clients want (mismatch of expectations). As a result, time (effort) and money are wasted. Extra time is needed to correct the developed software, which implies, more money spent and delayed launch. Software Engineering is a very specific field, very different from Business. Programmers speak a different language, and describe/approach problems differently. Client’s notion of “frame”/”dialog”/”security”/”screen”/”page”/”user” may be understood differently by a programmer. I am sharing my approach to understand what my clients want. This post will be helpful for clients to describe what they want, and programmers may use this approach to gather requirements from clients.
The key point is to be as specific as possible, and preferably, describe features in a measurable/testable way. “Building a beautiful e-Commerce website” is too vague, and you cannot objectively test if the website is beautiful. “User can make payment using PayPal” is en example of testable statement. The client should describe, from user’s perspective, what does a user sees on each page, and how user interacts with each page/screen.
Who
Describe users in terms of roles. Some of the possible user roles:
- Logged in user
- Registered user
- User account account
- Administrator
- Manager
- Buyer
- Seller
Questions to ask:
- What are the different types of users?
- What are the difference between each type of user?
How
Describe the functionality (from user’s perspective). Describe the actions performed by the user, and results of each action.
Examples:
- User signup for an account with username, password, email address information. Upon successful signup, user can login with the username and password.
- User specify search criteria (price, property type, location), and sees a listing of property that meets the search criteria.
Saying “User can purchase a product” is not enough. Programmer should work with client to break it down into steps, each step is equivalent to a screen. Describe the series of screens that a user will encounter, from selecting products to getting successful payment confirmation. For complex operations, it might be easier to use a flowchart to describe each performable action. A few rounds of iteration may be needed to break down the abstract actions into screens.
Questions to ask:
- What does the user do with the software?
- How does the user use the software?
Capturing User’s Input
When user has to input some information,
- List out all the fields (e.g. name, price, address, model number, …)
- Specify possible/tupical values/ranges of each field. It may be price range, or values that follow a certain format.
- Specify which fields are mandatory, which are optional.
From The User’s Perspective
It is important for programmer to describes features that is of values to the user. Usually users do not understand with is CMS, and do not cares about database and API. (Unless the targeted user of the software is a programmer.) Instead of talking about tables in database, describes the input fields visible to user. Describe what user sees/clicks/types on the page, not how programmer implements the software.
Use Visuals
It is true that a picture speaks a thousand words. Flowcharts, sequence diagrams, and wireframes are very powerful tools for communication requirements. Client may user existing software and websites are references. For each reference, client should describe why or which part of the reference describes what he/she wants.
Summary
Be as specific as possible, describe what the users see and do. Clients should describe features that can be objectively verified. Visuals are preferred over words.