The No-Spec Spec: Environment

This is part 6 in the series The No-Spec Spec

A lot of teams that do produce specs could benefit from adding this one: it’s a hidden piece that gets shuffled between Marketing, Development, and Support, often winding up on the floor between them. It’s often a short document, but the thinking that goes into it can be subtle and it’s often a point of disagreement. Get it on paper as early as you can and let it change as it needs to¹.

The Environment piece of the No-Spec Spec describes the context where the product is intended to operate. This can be pretty short; sadly, it’s rarely simple.

Although you should only include sections relevant to your project, Context (Environment) can include:

• Who is the user?
• What is the user trying to accomplish?
• Is the user the same as the customer? If not, who is the customer and what are they trying to accomplish?
• What is the timeframe the product runs in? Does it have an expiration date? Note that this is different from the product schedule. It is about how the business/regulatory/calendar environment affects the product. A game may need to ship in November for sales reasons, but that doesn’t mean playing it is tied to the calendar. Software for students, however, may be affected by school schedules in the target area.
• Is there a time constraint on execution? (Only at night, only while the store is open, must finish before opening of business, etc.)
• What hardware is the product running on?
• What OS does the product require?
• What other software is running on that hardware?
• What other business processes does the product interact with?
• What other products does the product interact with?
• What kinds of aftermarket extensibility does the product expect? (Note that this related to, but is not dependent on, the Capability document)
• What regulations control the product’s behavior?
• What kinds of support does the user/customer expect as part of normal use?
• What continuous billing or auditing does the product require?

In many companies, these answers are kept in different departments. In many companies, these answers are never written down.

Conceptually, this is a simple doc. The hard part comes when people try to pin the answers down².

Some sample answers (no, these are not for the same hypothetical product):

User	High-school or college student with a laptop or tablet that they take to class. Some functions require a tablet. (List tablet functions)
User’s goal	Have one or more chosen songs play while enjoying a social time out
Customer:	Owner of the jukebox
Customer’s goal:	Continual income from users paying to play music
Timeframe:	During school sessions (Sept-Dec and Jan-May in most places; list trimester schedule is appropriate)
Time constraints:	Software updates and new database contents must download and install (or rollback) by start of business
Hardware:	Server: (example servers) Client: (example clients)
OS:	Server: (list supported) Client: (list supported) Mobile: (list supported)
Other software:	Server: SQL Server 2008 or Oracle (version) Client: Software firewall, antivirus, SQL Server desktop, VPN, (list necessary support tools) Mobile: SMS, email
Other business processes:	Routine remote administration Regular cash auditing Regular removal of cash Regular on-screen income reporting and income split Reporting ad display and click-through
Other product interaction:	Our server software (list) Our billing and support tools (list) Ad network (which ones?) Third-party data feeds (list)
Extensibility:	Full UI replacement Added menu/toolbar items that launch third-party dialogs Automation from other software
Regulations:	HIPPA Compulsory license reporting Contractual license reporting COPPA
Support:	Quarterly db analysis and cleanup
Billing:	Monthly metered billing. We need to connect and read the use meter by the 5th of each month.

This is a pretty simple document (although you want more detail than the example above!). You may be surprised how many arguments break out over defining the answers, though. Get through them.

Then the answers will change. When this happens, you need to re-evaluate a bunch of things. At a minimum, re-evaluate the Behavior and the Capability documents. Most of the time, very little will change, but when it winds up being a big change you’ll be glad you didn’t miss it. And if the Behavior or Capability do change, re-evaluate some non-spec documents. At least validate that technical design and test plans are still correct.

Pay special attention to the user and customer goals. These are the primary downstream consequences of the Fit, Identity, Purpose, and Assumptions. Make sure everything else in the document supports those and make sure they are re-validated if the upstream documents change.

This doc is no less important than the others, but it is usually easier. Enjoy having it: you will find that it helps in unexpected ways.

---

1) Make a sign. Put it up where everyone can see it. Put these words on the sign: “Don’t get it right; get it written.” Really. Do it.

2) One product I worked on could only define the user as “anyone with a credit card.” That was pretty far from accurate, but it was even farther from useful.

---

Listening to: Nimpf – Lonesome Town – Cyber Punk Fiction

---

---