How to Draft a Specification or Requirements Document for a Contract

Many licenses and independent contractor agreements require a technical specification or requirements document describing the software or web service that one party must deliver to the other.Specifications and requirements are the standard to determine whether the developer has met its obligations, and therefore will be paid.They’re obviously critical.

For major software or internet projects, the review process (with comments from departments such as Product Management and Marketing, Sales, Engineering, Customer Support, and last but not least, Legal) assures that the specification almost writes itself.(Whether it is a good specification for a great product is never assured.)

It’s a different story for smaller projects.Sometimes product leaders or engineers calls me, saying they must produce a spec for a contract and don’t know where to start.Time and resources don’t justify a detailed review.They’ve been told that “everyone knows what’s needed” and they “only have to put it down on paper.”When facing that blank sheet (or empty screen), they just freeze up.

Here are some suggestions:

  • Describe what the product is intended to do.
  • Describe the hardware, software, connectivity (e.g. type and speed of network connection) and protocols / Application Programming Interfaces (API’s) required for the product to operate.Does the user need to obtain these separately (either via purchase or an open source license)?Are certain vendors or brands required?Don’t forget to specify operating systems and platforms, processor speed, and RAM and disk storage space needed.Tie the spec to current versions.Frequently the required third party components will be updated, which breaks the product.Is the developer required to fix the product to deal with the updates; can the developer charge extra for this?
  • Spell out the user environment and limitations, such as limits on the number of users, concurrent users, database records and database inquiries.
  • Response time limitations generally are important.It may not be worth specifying them too precisely, though.
  • Security, privacy and encryption features can create a poor user experience and even result in legal liability because they are regulated by U.S. federal and state law and foreign law.Be sure to consider these issues, or consult an attorney who can.
  • Does the design or architecture have inherent limitations?Better to say so now than to second guess and argue later.
  • In general, try to write down any important but unstated assumptions.
  • Mockup screen shots often are helpful, but too much detail can be cumbersome and reduce the flexibility of the development effort.
  • If the spec relies on another document (e.g. a standard), be sure to identify it clearly by name, version number and date.
  • Describe any special test protocols or testing required.

Here are some examples, with various levels of detail:

Legal issues may require a different level of detail than a developer otherwise would provide solely for technical reasons.  For example, if the product uses unproven technology, the specification may need less detail so that the developer has legal “wiggle room” for changes during the development effort.1

Sorry, comments are closed for this post.