Documentation

Define the requirements

While the purpose statement is a sentence or two about the basic scope of the project, the requirements list the specific business needs. Requirements can span from one page (for a one-week project) to 50 or more pages for projects that have a lot of data points. A project of one man-year in size can often list requirements in 5-10 pages.

People often confuse "design" with "requirements". They are very different. The table below can help distinguish the two. The table also separates out technical requirements (relating to the available resources and policies, and pre-existing limitations) from business requirements (all others).

Business Requirements
  • List individual data points, like first name, last name, date of sale, etc.

  • Define roles and permissions; for example, that sales reps will not be able to modify product information.

  • List externally imposed requirements, such as by a government agency.

  • Define the data points that you need to get out of the system in the form of reports; for example, sales volume by region and date range, sale detail, and so on.

  • List or show examples of visual requirements insofar as they are truly business needs, such as the use of logos and conformance to presentation standards.

  • Generally describe the data entry processes required, particularly if the entry is divided out by job function and security considerations.

Defer until design phase
  • Show screens with graphics.

  • Show how data will be laid out on a screen.

  • Define how the user will interact with the product.

  • Specify languages and tools. (Even the choice of whether it should be an installed application or a web site should be deferred to the design stage!)


Technical Requirements
  • List available hardware and software, and other limitations imposed by prior choices of IT staff; for example, if the product must run under Windows.

  • Explain which existing products and datasets the new system has to connect to, and how they must connect, including web sites, legacy systems, and accounting systems.



Modeling data in the requirements phase

A "data model" as explained in a later section, is an exact specification of data types, and properties of those types. For example, a "person" is a data type, and "date of birth" is a property of a person. The requirements phase should be the first step in designing the data model, but there is no need to design it all yet. For example, you could list in requirements:

Store households in survey area. Store the drivers in each household (name only), and their vehicles (year, make, model, VIN). Each vehicle is stored with the household, not attached to a particular driver.

In the data model design, you will later formalize this requirement to:

type "household" has properties (address)

type "driver" has properties (reference to household, first name, last name)

type "vehicle" has properties (reference to household, year, make, model, VIN)

And you would include specifics like maximum lengths and data types of each property. The main point here is to avoid mistakes, like erroneously associating the VIN property to the person type. Also, be clear on what goes with what - in this case, the vehicle could have been assigned to a specific driver instead of the household. If that were done, you would have to decide how to record vehicles with multiple owners. Deal with the relationships in the requirements phase, and the specifics of each property later.

Visual layouts

It often helps to draw screens on paper, especially for visual thinkers. This can help you think of all the things that will need to be entered and what the relationships between the data are. But after you list everything, throw away the drawings, because they aren't truly business requirements. A common mistake in software development is the attempt to follow early drawings after requirements change or after the design phase results in the need for a different data entry process.

Contracts

In some cases, requirements are used as the basis of contracts. If you are the buyer, it's a good way for you to hold the vendor to the results that you are paying for.

However, requirements take time - up to a quarter of the total time spent on a project. If you expect the vendor to write requirements before signing a contract, the vendor is assuming all the risk. Companies that do that have to charge you eventually in some way to make up for that risk and expense.

On the other hand, if you expect the vendor to provide a fixed quote before writing requirements, they will have to charge a lot extra up front for taking the risk of not knowing the eventual scope of the project.

There are a couple ways around this: One is to pay for requirements separately, so that both parties have limited and shared risk, and you end up paying only for the requirements that end up in the scope.

The second solution to this dilemma is to write a contract for the total project based on preliminary requirements, which only characterize the quantity of work rather than the details. For example, "the system will account for 30 data points, and have up to 8 report formats". If in the course of the final requirements process, you find that more work will be needed, both parties have a fair basis for changing the price.

(c) 2014-2015 Divergent Labs, Inc.