This blog post is part of a series on non functional requirements, and how the NFR take most of the effort.
The scenario
You want a third party to implement an application package to allow people to buy and sell widgets from their phone. Once the package has been developed, they will hand it over to you to sell, support, maintain and upgrade and you will be responsible for it,
At the back-end is a web server.
Requirements you have been given.
- We expect this application package to be used by all the major banks in the world.
- For the UK we expect the number of people who have an account to be about 10 million people
- We expect about 1 million trades a day.
See start here for additional topics.
A word of wisdom
A wise person said – never assume , always state the obvious, because what is obvious to you may not be obvious to them.
Of course you want documentation provided by the development team. How hard is it to specify what you need?
The first “obvious” thing is you want soft copy of all documentation source and tools to be able to update and print new versions. “Provide documentation” could be interpreted as send you a print-out of the documentation, which you then photocopy – but cannot update or reprint.
The second obvious thing is that you want the documentation to be useful. Much of the documentation available for products, covers all you need to know – but not in a consumable format. For example with the instruction book for my new car, how to start the engine was on page 110!
With software you may get a book with all of the commands, or all of the APIS, in alphabetical order. When you are new to a product you often need just a few commands or APIs to get you started, and be able to evaluate the product. If you have a web page with the options for a particular command, it would be good to have a buttons called “first time”, “normal usage”, and “expert usage”. If you click on the “first time” button all of the optional or expert options are hidden.
Know your audience.
I worked with a product that had 150 pages of configuration instructions, before you could start the product. When you did start using it you often got an unhelpful message “Error in ££BOPEN file not set up properly”, and you were not told which file was not set up.
If you were an expert in the platform, and knew where to look, you could find additional information.
Customers reported many problems getting it going.
I worked with the developers and they rewrote the installation instructions. The first steps were to create a startable instance with no useful function. This took about 2 sides of paper. Once this started, we added in a component, and checked that it started, then add another component, and checked that started and so on. The users loved it, and the number of problems reported dropped significantly. If the product started; then you did more configuration and if it did not work, it was clear where to look – something you did in the last few pages.
We also provided good samples which could be used out of the box. These had instructions called “extending ….”
What is interesting to the user
if you provide web site for your documentation monitor which pages get hit, and which are not referenced. You can then review the popular pages, and perhaps update them.
If a particular message gets many hits. Enhance the “what to do now” section, or change the code to produce better diagnostics.
ColinPaice 