Documenting specification requirements

Now that you've assembled your information about the data, people, and technologies affected by your application, it's time to write up a software specification. Software specifications can range from very formal, contractual documents that include time estimates and deadlines to a simple set of descriptions of what the programmer intends to build. The purpose of the specification is to give everyone involved in the project a point of reference for what the developer will create. It spells out the problem to be solved, the functionality required, and the scope of what the program should and shouldn't do.

Your scenario is rather informal and your application is simple, so you do not need a detailed formal specification in this case. However, a basic write-up of what you know will make sure that you, your employer, and the users all understand the essentials of the application you will be writing.

Contents of a simple specification

We'll start our specification with the following outline of the items we need to write:

• Description: This is one or two sentences that describe the primary purpose, function, and goals of the application. Think of it as the program's mission statement.
• Requirements: This section is a list of specific things the program must be able to do in order to be minimally functional. It can include both functional and non-functional requirements.
  • Functional requirements are concrete goals that the program must achieve; for example, the business logic that it must perform or the output format it must produce. Listing these helps us know when our program is ready for production use.
  • Non-functional requirements tend to be less specific and focus on user expectations and general goals, for example, usability, performance, or accessibility requirements. Although these aren't always measurable goals, they help to guide the focus of our development.
• Functionality not required: This section is a list of things the program does not need to do; it exists to clarify the scope of the software and make sure nobody expects unreasonable things from the application. We don't need to include every possible thing our application won't do; naturally, our program won't make toast or do the laundry. However, if there are features we are not implementing that users might reasonably expect, this is a good place to clarify what won't be done.
• Limitations: This is a list of constraints under which the program must operate, both technological and human.
• Data dictionary: This is a detailed list of the data fields in the application and their parameters. A data dictionary can get quite lengthy, and may be worthy of a document of its own. It will not only be useful during the development of our application but will become a critical reference to the data produced by the application as the application expands and the data gets utilized in other contexts.

Writing the ABQ data entry program specification

You could write a specification in your favorite word processor, but ideally the specification should be treated as a part of your code; it will need to be kept with the code and synchronized with any changes to the application. For that reason, we're going to write our specification in our code editor using the reStructuredText markup language.

For Python documentation, reStructuredText, or reST, is the official markup language. The Python community encourages the use of reST to document Python projects, and many packaging and publication tools used in the Python community expect the reST format. For an in-depth coverage of reST, see Appendix A, A Quick Primer on reStructuredText, or see the official documentation at https://docutils.sourceforge.io/rst.html.

Let's start with the Description section of our documentation:

======================================
 ABQ Data Entry Program specification
======================================
Description
-----------
This program facilitates entry of laboratory observations
into a CSV file.

Now, let's list the Requirements. Remember that functional requirements are objectively attainable goals, like input and output requirements, calculations that must be done, or features that must be present. Non-functional requirements, on the other hand, are subjective or best-effort goals. Look through your findings from the last section, and consider which needs are which. You should come up with something like the following:

Requirements
----------------------
Functional Requirements:
  * Allow all relevant, valid data to be entered,
    as per the data dictionary.
  * Append entered data to a CSV file:
    - The CSV file must have a filename of
    abq_data_record_CURRENTDATE.csv, where CURRENTDATE is the date
    of the laboratory observations in ISO format (Year-month-day).
    - The CSV file must include all fields
    listed in the data dictionary.
    - The CSV headers will avoid cryptic abbreviations.
  * Enforce correct datatypes per field.
Non-functional Requirements:
  * Enforce reasonable limits on data entered, per the data dict.
  * Auto-fill data to save time.
  * Suggest likely correct values.
  * Provide a smooth and efficient workflow.
  * Store data in a format easily understandable by Python.

Next, we'll reign in the scope of the program with the Functionality Not Required section. Remember that this is only an entry form for now; editing or deletion of data will be handled in the spreadsheet application. We'll clarify this as follows:

Functionality Not Required
--------------------------
The program does not need to:
  * Allow editing of data.
  * Allow deletion of data.
Users can perform both actions in LibreOffice if needed.

For the Limitations section, remember that we have some users with physical constraints, as well as hardware and operating system constraints. It should look something like this:

Limitations
-----------
The program must:
  * Be efficiently operable by keyboard-only users.
  * Be accessible to color blind users.
  * Run on Debian GNU/Linux.
  * Run acceptably on a low-end PC.

Finally, we will write the data dictionary. This is essentially the table we made previously, but we'll break out range, data types, and units for quick reference, as follows:

+------------+--------+----+---------------+--------------------+
|Field       | Type   |Unit| Valid Values  |Description         |
+============+========+====+===============+====================+
|Date        |Date    |    |               |Date of record      |
+------------+--------+----+---------------+--------------------+
|Time        |Time    |    | 8:00, 12:00,  |Time period         |
|            |        |    | 16:00, 20:00  |                    |
+------------+--------+----+---------------+--------------------+
|Lab         |String  |    | A - C         |Lab ID              |
+------------+--------+----+---------------+--------------------+
|Technician  |String  |    |               |Technician name     |
+------------+--------+----+---------------+--------------------+
|Plot        |Int     |    | 1 - 20        |Plot ID             |
+------------+--------+----+---------------+--------------------+
|Seed        |String  |    | 6-character   |Seed sample ID      |
|Sample      |        |    | string        |                    |
+------------+--------+----+---------------+--------------------+
|Fault       |Bool    |    | True, False   |Environmental       |
|            |        |    |               |sensor fault        |
+------------+--------+----+---------------+--------------------+
|Light       |Decimal |klx | 0 - 100       |Light at plot       |
|            |        |    |               |blank on fault      |
+------------+--------+----+---------------+--------------------+
|Humidity    |Decimal |g/m³| 0.5 - 52.0    |Abs humidity at plot|
|            |        |    |               |blank on fault      |
+------------+--------+----+---------------+--------------------+
|Temperature |Decimal |°C  | 4 - 40        |Temperature at plot |
|            |        |    |               |blank on fault      |
+------------+--------+----+---------------+--------------------+
|Blossoms    |Int     |    | 0 - 1000      |No. blossoms in plot|
+------------+--------+----+---------------+--------------------+
|Fruit       |Int     |    | 0 - 1000      |No. fruits in plot  |
+------------+--------+----+---------------+--------------------+
|Plants      |Int     |    | 0 - 20        |No. plants in plot  |
+------------+--------+----+---------------+--------------------+
|Max Height  |Decimal |cm  | 0 - 1000      |Height of tallest   |
|            |        |    |               |plant in plot       |
+------------+--------+----+---------------+--------------------+
|Min Height  |Decimal |cm  | 0 - 1000      |Height of shortest  |
|            |        |    |               |plant in plot       |
+------------+--------+----+---------------+--------------------+
|Median      |Decimal |cm  | 0 - 1000      |Median height of    |
|Height      |        |    |               |plants in plot      |
+------------+--------+----+---------------+--------------------+
|Notes       |String  |    |               |Miscellaneous notes |
+------------+--------+----+---------------+--------------------+

That's our specification for now! The specification is very likely to grow, change, or evolve in complexity as we discover new needs, but it gives us a great starting point for designing the first version of our application.