Week 6: Software development methodologies and document maintenance -- case study
User requirements specification (URS)
This document is usually developed some time in the early part of the project, and is often a collection of user "wish lists" - things the users would like to see happen. URS also include input from business analysts.
HairSys URS
HairSys is a planned new system for hairdresser salons, which allows recording of appointments, planning of new appointments, and analysis of customer patterns of use.
Here are some of the results of the user interviews:
- "I want to
be able to keep track of each customer, including their name, address,
date of birth (so I can remind them to come in before their birthday
celebration), and other details."
- "I use a
lot of casual stylists, and I need to keep track of their details, as
well as their specialisations; often I need to call a casual stylist
in in a hurry, so I need their phone number in the computer."
- "When a customer
calls for an appointment, they often specify which stylist they want,
so I need to be able to say when that stylist is next available. Or
sometimes they just want the next slot, and don't care who is on."
- "I like to
look back over the customer's history with them, show them what they've
had done and when, and which stylist worked on it."
- "I want each appointment to show up automatically in my accounting system, so I don't have to enter it twice."
User Requirements documents are not usually much use for gathering information about how software works, but they are very useful input for audience and task analysis.
Next stage: data model
The next stage of the process is often to build a "data model", which is a diagram showing what kinds of information is to be stored. Computers store information in databases, which are arranged a bit like spreadsheet tables:
Each row in the table is called a 'record', and is equivalent to a row in a spreadsheet table. Each column is called a 'field', and is equivalent to a spreadsheet column.
Often two tables will be linked together by a common field:
Here the field 'Name' is used to link the two tables. The top table is called 'Mother', and the bottom table is called 'Child'. I've drawn curvy lines just to show which names match.
Where there are a lot of tables, a diagram is often drawn which shows just the tables and the relationships between them (without the field or record details). For example:
This is all very well, but it doesn't show the relationship - the fact that there is a field in common. The way to show this is with a line:
It is common to add bits to the ends of the line to be more specific about the relationship, for example this:
means that each record in 'Mother' can be attached (by having the same value in the 'Name' field) to any number of records in 'Child', but that each record in 'Child' can only be attached to one record in the 'Mother' table.
Here's another example (we'll discuss what it means in the tutorial):
The data model is not usually very useful for user documentation research, but it is a good way of getting your head around what a particular piece of software covers. Some data models run to hundreds of pages.
Data dictionary
The next stage is to fill in the details of the fields in each table (but not individual records, of course). In older computer systems it was necessary to specify not just the name of each field, but also its length and its type.
There are many different types of data field, each capable of holding only a certain type of information:
- integer: able to hold only a single whole number
- real: able to hold only a single number with decimals
- date: can only hold a date (although often a date and time)
- string: can hold any text, including numbers and punctuation
- boolean: can only hold the values 'True' or 'False'
A typical data dictionary looks like this:
The table 'Student' has four fields. The first two hold the given and surnames for the student, and each can hold up to 15 characters (letters, spaces, punctuation, whatever). The date and boolean field types don't need lengths, because you don't get a choice over how long they are (dates are sometimes 6 characters, which is why we have a year 2000 problem, and boolean fields are usually one character).
Data dictionaries are goldmines for user documentation research, because each 'field' on a screen is usually a 'field' in a table somewhere in the database. If you can find one with more than scratchy comments against each field, that's even better.
Assignment: come up with a data dictionary for the HairSys system.
Functional specification
The next stage is to come up with a complete specification which says exactly what the software will do. Where the software is being developed for a specific customer, this "Functional Spec." will often be "signed off" by having the customer sign a copy to indicate that they agree with the content of the specification. In this way, arguments about what the software should and should not have been capable of doing can be resolved later.
In theory, the Functional Specification should be updated as the design of the software proceeds, but this is often not done, leaving the FS as an initial 'snapshot' of what the software was supposed to look like originally. However, the FS is often a very useful source document for developing user documentation.
The kind of thing you will find in a FS are statements like:
"The system will allow the creation of student records as per the attached data dictionary."
... pretty woolly stuff. Sometimes they are more specific:
"Entry of dates will be in the format dd/mm/yyyy: dates entered with less than two year digits will generate an error."
Assignment: come up with a Functional Specification for HairSys
Program specification
The next level down is the Program Specification, which is (in theory) what the programmer actually needs to know in order to build the software. Up to now, most of the work will have been done by people with "analyst" somewhere in their job title ("programmer/analyst", "business analyst", "analyst/programmer").
The Program Spec. spells out in detail just what function each part of the program needs to perform. It often includes screen designs. Here's a Mickey Mouse Program Spec for a single program:
Program name: MMEDIT
Files: see data dictionary
Screen shot:
Function: When first called, this program retrieves the first record from the table 'Mouse' and displays it. The user can edit the contents of the fields, and then chooses either 'Cancel' or 'OK'.
If the user chooses 'Cancel', a message appears saying "Error: can't cancel." If the user chooses 'OK', a message appears saying "Can't complete: please choose Cancel."
Programs specs are often very useful as source material for developing user documentation. Unfortunately, they are so useful that many developers think that they can be used instead of user documentation. But of course they can't, because they view the system from the system's perspective, rather than the user's.
Assignment: come up with a PS for HairSys
Testing
There are a number of different types of testing that take place during a software development project, but the one that's most relevant to user documentation is Acceptance Testing.
This happens when the developers think that the software is finished, and present it to their customer for testing. Acceptance testing is a highly formal affair, and an Acceptance Test Specification is often drawn up and "signed off" before testing begins (often, before software development is complete).
Acceptance Testing is carried out by running through a series of defined tests with defined test data, and observing the results. This is often done in the presence of representatives from both the developer and the customer (so they can both keep each other honest).
Acceptance Testing is particularly significant for user documentation development because:
- it is the point at which the developer feels the software is finished; they will try to keep you out of their hair until this point
- it is important to have the user documentation completed at acceptance testing - because the documentation should be part of the test; so you must be in the developer's hair very much before this point!
When to start doing documentation?
The single most often asked question from software developers is: "When should you start doing user documentation?". The answer is that the planning should be carried out as early as possible, so that the size of the documentation effort can be estimated.
Once that has been done, you can work back from the acceptance test to figure out how late you can start writing the doco, and still get finished in time for delivery of the software. Of course, 99.999% of software development projects run late, so you will often have more time than you think you are going to have.