Documentation
What is it?
This section will get you to create a simple user guide. It will also assess your on-screen help which is why it was so important to add it.
Note – If you have failed to complete the system you can still get full marks on this section as long as you base the user guide on the design!
What does it contain?
Note – This should be a standalone document!
- Title page
- Table of contents
- Hardware + software requirements
- Installation guide
- Getting started / step by step guide to main features
- Backup
- Troubleshooting guide
What does each section contain?
Hardware and software requirements
You should have already produced this during analysis so it will be a copy and paste job! You will need to state –
- The minimum specification of the PC which can run your software
- CPU speed
- Memory size
- Hard drive space
- Note – the above will be based on your pre-requisite software such as the Java virtual machine or .net libraries. Or even tomcat or apache.
- Any other specific hardware (you can ignore mouse/keyboard etc)
- Software requirements including
- Host OS
- Any interpreters / libraries which need to be installed
- Any other required software
Ensure you format it into its own section.
Installation guide
It is unlikely you will have made a install wizard for your software (if you have well done!). You need to explain how to install the software onto the target. This includes installing any pre-requisite software first. For example a Java program would need Java virtual machine installed which would need to either be downloaded or included on the install media.
You also must clearly state how the user will get the final product. Will it be on CD or memory stick?
You must say –
- Where any pre-requisite software can be found
- How to install this software
- Where to copy your work to (what needs to be copied)
- How to start it off.
It may be worth making some simple BAT files (or script files) to do this to make the install guide simpler. They are easy to make. Something like
cp –r myProjectFolder ~/myProject
Would, on linux, copy a folder called “myProjectFolder” and place it in the users directory in a folder called “myProject”. Windows would be something like
Copy –r myProjectFolder c:/myProject
Note – I do not know if the above windows command is correct. I do not use windows and I am too lazy to test it! It is something like that!
Getting started / step by step guide
Note – Only do the MAIN features otherwise you will be here for a while!
For each of the main features –
- Copy the screen design or final screenshot of that form
- Say how to use it in a step by step manner.
- Comment on expected validation rules.
You will have seen any piece of software or hardware will have a getting started guide. The best way to do this section is to have a look at one of those and emulate it.
Backup
Here you should describe how the system should be backed up and how often. If your system is automated then explain this. Otherwise say exactly what files need to be saved in order to back up the data. A step by step guide with screen shots would be helpful.
Troubleshooting guide
This should be in the form of a table as shown below –
Problem |
Symptoms |
Solution |
Program will not start |
|
|
Can not log in |
|
|
As you can see the problems are clearly stated with symptoms and solutions. You do not need to write loads in this section but you do need to be specific!
You should have at least 4-8 entries in this table. Errors can range from unable to add things to the database, problems loading the program or logging in or common validation error messages.
Mark boundary
8–10 marks |
Candidates will provide detailed and accurate documentation. The documentation will be well presented, in a structured and coherent format. The documentation will cover all aspects of the system, with no omissions, including installation, typical use, troubleshooting, and backup. The on-screen help and supplementary documentation makes a complete guide to the solution and is well presented and easy to follow. Subject-specific terminology will be used accurately and appropriately. There will be few, if any, errors of spelling, grammar and punctuation. |
4–7 marks |
Candidates will provide clear documentation. The documentation will be well presented. There is clear on-screen support to enable the end user to use the system. The supporting documentation and on-screen help is well presented and covers most aspects of the system operation with only one or two omissions, eg troubleshooting or backup. Some subject-specific terminology will be used. There may be occasional errors of spelling, grammar and punctuation. |
1–3 marks |
Candidates will provide superficial documentation, with weak supplementary user documentation covering few aspects of the system. The information will be poorly expressed and limited technical terms will be used. Errors of grammar, punctuation and spelling may be intrusive. |
High mark boundary
- Stand alone document with table of contents and title page.
- The document uses clear sections and they are in a logical and coherent order.
- All elements are present.
- On screen help is clear and well presented. The guide and on screen help combined should be sufficient to explain all of the main tasks of the system.
- Clear backup guide
- SPAG
Middle mark boundary
- Stand alone document with table of contents and title page.
- The document uses clear sections and they are in a logical and coherent order.
- Most elements are present but may be missing small sections such as trouble shooting.
- On screen help is clear and well presented. The guide and on screen help explains most of how the system is used.
- SPAG with the occasional error.
Low mark boundary
- Stand alone document
- The document is vague and does not explain the system.
- Most elements are missing or poorly completed.
- On screen help is poor or missing.
- Poor SPAG
Top tips
- Make sure everyone of your main features has a step by step guide.
- Use screenshots to help explain the features.
- Assume the person using your system is a bit thick. Computers seem to make fools out of us all at some point!
- Make sure you do this in a separate document!