Arguably the most important component to professional application development begins before a single line of code has been written. Spending the necessary time generating requirement documentation provides a road map, which will guide your development process along a smooth, efficient path. Take out the guesswork; get it done more effectively, saving both time & money.
An obstacle encountered by many in programming / development, is the notion if you’re not head-down, writing code, you’re not being productive to the project. Quite the contrary. Studies show between 40% and 60% of all defects found in software projects, can be traced back to errors made while gathering requirements. * CODE Magazine - codemag.com
Much as a good construction architect will create blueprints of additional room on the back of a house before hammering one nail, professional software developers must follow the same process.
Benefits of spending adequate time analyzing your future project system's deliverables and scope can be summarized by:
- Total project development costs are less
- Increased system flexibility
- Increased system scalability
- Increased abilities to estimate project work task activity hours & associated costs.
Discovering issues and problems in the planning stages of application development, is much easier and less costly to rectify than after code has been written. Once programming has initialized, decisions are made with an eye towards the future, and developers will build off the code base. When that code base foundation shifts, say a key sub-component is inadequate and needs significant re-factoring, all code lying on top will require a costly re-factor.
The goal in pre-coding development activity is to minimize (or hopefully eliminate) the gap between what software developer’s believe they’re building, and what the users expect to receive.
“Over Budget” is a nasty phrase. Similarly, planning and estimating development time as those in the business world know all too well, has wide, swinging margins of error on each side. As a development team, we want to give the right estimate to land the project and not work gratis off initial time & resource miscalculations. Much the same a project manager who’s consistently wrong in submitting planning budgets to upper management will likely be frowned upon if not re-positioned. By spending the time to adequately define all components of a system development builds, we can reduce budgeting guesswork and learn a more true value of a team’s output metric.
So how do we achieve these pre-coding, total project benefits? Requirements Gathering and Use Cases.
Requirements are text documents which provide a clear, documented outline of what software developers aim to build.
Requirements gathering falls into two main categories; Functional Requirements and Non-Functional Requirements.
Functional requirements are clear, concise descriptions of individual tasks the software should perform.
Ex. the system should re-calculate total product bundle price when an individual product price is adjusted.
Functional requirements should define the scope of the system, and how far the system should (or should not) reach in it’s responsibilities.
Ex. the system should only display lists of all products grouped by Title, Date Created, and Product Owner. It need not group by any other data field in summary scenario.
Functional requirements should describe a system’s relationship to parallel or connected systems.
Ex. the system should update all product bundle data when an adjacent data update application runs on our company's servers each week.
Functional requirements define business rules. Business rules will be unique to each organization, and essentially are a set of rules any organization’s system must always follow. Typically these are the most important functional requirements gathered.
Ex. Any bundled collection of products 10 or greater will receive a 15% discount on the package price.
Functional requirements will define the data models and data sets the system uses.
Ex. The system will use data objects retrieved from the following service endpoints http://myorganization.com/dataset1 and http://myorganization.com/dataset2
Lastly, good functional requirements should be extremely clear, and verifiable. Is the requirement testable with a definitive outcome?
Ex. When viewing the main product list details screen, the UI should only show product grouping by Title, Date Created, and Product Owner.
Non-functional requirements deal with the visual nature of the system. How the application looks, feels, it’s design, color scheme, layout, etc.
Ex. All pages should be branded with organization logo in upper left corner of page, and use company color theme on all sectional landing pages.
Non-functional requirements also detail the intended platforms in which the system will live & operate.
Ex. Our application will function across the following browsers (Chrome, Safari, Firefox, Internet Explorer 9 and above). The application should function in targeted platforms mobile, tablet and desktop.
Non-functional requirements can also be used to describe a system’s maintainability.
Ex. The application will use a bitbucket repository from which developers interact, and from which scheduled releases will be delivered to end users.
Once the system requirements have been satisfactorily collected and documented, the next step before starting the coding process is to run our collected requirements through "Use Cases".
Use Cases are also text documents which describe system scenarios.
Ex. once a user logs into our system, a service endpoint retrieves data and sends the user to a page dependent upon whether new, updated product data exists or not.
‘Scenarios’ are interactions between the System being created, and ‘Actors’. Actors are not necessarily end-users, they can also be adjacent systems or non-persons.
Ex. In a certain scenario, say the ‘Actor’ is in fact an end-user and clicks the ‘Update’ button after editing a suite of products in a system view page.
The focus for Use Cases is on the system reaction. How does the system react? What does it do? What should be calculated? What should be displayed? Which page should the user be taken to?
A good approach for creating documented Use Cases, is generating a 2-column template for each Use Case Scenario. The left-column ‘Action’, and right-column ‘Reaction’. The list of reactions will determine the development, coding path.
'Use Case Diagrams' are another valuable visual tool used in constructing a system’s Use Cases. Typically these are represented by a stick figure representative of an end-user, and arrows pointing to ‘circles’ which are Use Case objects. Basically creating such a visual tool provides a macro-level overview of the system and it’s intended features.
How to create effective Requirements and Use Cases?
Planning development time for pre-coding requirements gathering and use case scenarios is an important first step, but only as effective as the quality of data collected. How do we ensure we get the best possible Requirements and Use Cases?
Consult current system ‘experts’ and developers with experience the field. Get information on the current system and process limitations and why those limitations exist. What’s caused them? Is it the data model, the UI, technology limitations? Directly diagnose problem areas as well as what the current system does really well. What are the strong points, to build from and accentuate?
Also equally important is to interview, observe and consult end users. Directly observe end users interaction with the current processes in place. What’s their behavior in the system? What are their frustrations, their gripes, areas which seem to make their job difficult? What are the end user’s thoughts on how the system, especially the UI should perform? In a perfect world, how would they want certain Use Cases Scenarios to work?
Experienced development teams stress the importance of requirements gathering and generating use cases in planning their project time line. The reality in prematurely jumping directly into coding a vague project, truly lies in the pocketbook. It’ll cost valuable time, resources, and the opportunity costs of pushing back on future projects when programmer’s efforts are either misguided or circular in nature. It’s expensive.
It boils down to business, and the quicker will survive and flourish. Developing a well-established system for building corporate level applications requires seeing the big picture, and developing/writing code in accordance with an intelligent, well-defined road map. Take the time to think it out.