Sie sind auf Seite 1von 16

Documentation

Documentation is usually an area that is not done particularly well. Guides are usually difficult to follow, presented badly and could not be used by the end user. The documentation is a standalone document, it should not be part of the numbered page sections of the project, but presented in a separate binder/section. It should contain appropriate screen shots and instructions for installing, maintaining and using the system. As a test, you might give the documentation and the system to someone who has never used it and ask them to use the system via the documentation. If they have problems, then you need to go back and revise the documentation. Because the technical user guide is a repeat of the development, you must include everything in the technical user guide but in the development section you can give page numbers from the technical user guide where evidence can be found. For example, instead of printing out your annotation of code twice, you can include it in the technical user guide and then in the development section, say: The annotated code can be found on pages 23-35 of the Technical User Guide

Overview of Section
The technical documentation is designed to offer maintenance of a system and to give enough information so that the system can be upgraded. A lot of the material required will have been created elsewhere in the project and it is merely a question of assembling it in the correct format. The user guide is for the end user and should detail not how to use the underlying software or system, but how to use the system that you have created. It must include all possibilities and a troubleshooting and start-up guide.

Technical
The technical documentation is intended to be a standalone document that can be used to maintain and upgrade the system. This means that everything about the system must be documented. The technical guide should not include any development work, but contain details on the final product. This means that you cannot write it, in theory, until you have completed the project as changes might be needed to be made to the product at any stage, included user acceptance at the very end. Below is a list of what you might find included in the guide, but it will vary from project to project. There is also a cross referenced list of where in the project you might have already covered the item in question. Item to be included in Technical Guide Hardware and Software Specification Backup and Recovery Technical Procedures Data Structures (data models, relationship diagrams) Data Flow Diagram Input Documents/Screens Tables and queries underlying reports and forms Output Documents/Screens Project Cross Reference Analysis: Software and Hardware Selection Design: Nature of the Solution Design: Nature of the Solution Design: System Diagrams Design: Nature of the Solution Design: Nature of the Solution Design: Nature of the Solution

Annotated Code Listing (inc formulae) Data Dictionary Security of the System Error Messages

Software Development Software Development Software Development/Design Design: Nature of the Solution Figure 4.1

Hardware and Software Specification This is a complete list of all of the hardware and software required to run the system. This can be taken directly from the analysis (although the justification is not required). Include a statement saying that this is the minimum specification required. Backup and Recovery Technical Procedures This must be included. It needs to detail what files are being backed up, where they are being backed up to and what happens in the restore process. If necessary, it should detail who has the security to perform a backup and restore. Data Structures (data models, relationship diagrams) These can be copied from the Design section as they will relate to the new system. Apart from copying them across, nothing more is needed. Data Flow Diagram/Sate Transition Diagrams Any diagrams must be about the new completed system. They should not have anything to do with the old system. For details of the specific diagrams, refer to the appendices. Input Documents/Screens All of the input screens must be included. These are in more detail than the ones included in the user guide as they should contain the names used for all of the elements on the screen. For example, in Access/VB/HTML you need to detail all of the names of the labels, text boxes, buttons etc. This needs to be done for every different screen. Below is the sample screen from a technical guide. It is a database form for entering a company name and address into the database. Along with the form, there is the underlying table upon which the form is based and the table in standard notation. Sample Design Screen from Technical Guide

The form contains: 1. LblTitle 2. LblCountCompanies 3. TxtCountCompanies 4. LblCompaniesInformation 5. LblComanyName 6. TxtCompanyName 7. LblCompanyAddress 8. TxtCompnayAddress 9. Cmdirst 10. CmdNext 11. CmdPrevious 12. CmdLast 13. CmdUpdate 14. CmdClose 15. FmCompanies 16. ImgIcon

Title for the form Label for the number of companies Text box for the number of companies Label for the companies subtitle Label for the company name Text box for the company name Label for the company address Text box for the company address Button to goto first record Button to goto Next record Button to goto previous record Button to goto last record Button to update record Button to close form Name of the form Icon in top right hand corner

Figure 4.2 This is only one way of presenting the technical guide, it may be that for you, it is appropriate to printout the screenshot and then handwrite the annotation. Some database packages will printout a textual description of the forms, tables queries etc. This is acceptable to hand in, but you need to annotate the printout to highlight the names of objects and controls and to tie in the printout with a screenshot.

Tables and Queries Underlying Reports and Forms You must also detail the table structure and any queries that are used. You will have already shown the underlying structure in the design and a screen shot will allow the two to be tied together, but it would be useful to have the table shown in standard notation. It is unlikely that any query or table will appear directly, so it will be necessary to show how they are used and how the data is to be viewed- whether this be by form or by report.

Sample Table for Companies Form COMPANY(CompanyID, CompanyName,Address))

Figure 4.3 Any documents that are entered must be included and you need to show the data entered into the form (include a blank and a filled in form) and where it is inputted into the system.

Output Documents/Screens Any output screens (these include screens that show results of queries, sorts etc) need to be detailed in the same way as the input screens. In addition, you need to show where the information for the output comes from. Any documents that are printed should be included. Annotated Code Listing This is a printout of any code that has been used in the project. It may include: Formulae in a spreadsheet HTML Code Macros Coding No code should be included unless it is annotated. Each module/procedure should have a correct identifier and commented heading in line with the directions given in the software development section. If you have lots of sections of code that do that same thing for example a next button on ten forms, it is not necessary to include ten copies of the code, one copy will do and a reference to all the other areas that use the same code.

Example of Annotated Code from Companies Table

*************************************************** Display updated company record 26/06/01 Version 1.3a Writer: G Millbery *************************************************** Private Sub DisplayCompany() txtTitle = rcompany![Company Name] txtAddress = rcompany![Address] End Sub
Figure 4.4 Where variables have been used, you must list them and state their data type and what they will hold. You also need to state whether they are procedural, form or modular variables. If you have followed the naming of variables conventions, the scope and type of the variable should be known from the variable name. The following outline can be used:

Example of Variables Table Name PIResponse Data Type Integer Scope Procedural Purpose To find out whether the user clicked OK or Cancel To find out which field the user has requested to search on. Found In Proc_Search Proc_List Proc_Type Proc_Search Module_Search

IMSearch

Integer

Module

Figure 4.5 Data Dictionary If you have used a database, you need to include the data dictionary. This will include the relationship diagrams, the structure of the data the tables and fields in the tables, the name and description of each data item, restrictions on data items (validation) and the security rights to the data. It may be that a lot of the items included in the data dictionary are included elsewhere. In this case, it is not necessary to duplicate them. Security of the System If you have any security, such as passwords, logon names, access rights to data, then these must be listed. The table used in the design process can be used here to detail access to different forms etc. You need to detail how to add people to the system and change the access rights of different forms etc. If necessary, also show the users how to change the passwords. Error Messages The listing of unique error numbers and the associated error messages needs to be included.

It is important that the document is easy to read and follow and that all elements of the project have been covered.

User
The user guide should include a collection of screenshots and associated text. You must never include a screenshot unless it is annotated in some way. You must also make sure that the user guide is a sequential document. This means that it follows the standard routes through the system that the user will use. The user guide is a guide for use - it should be an every day reference guide that users of all levels can use. It may be that there is in fact more than one document. For the highest band, you must include some documentation that exists only on the computer, such as on line help. It is possible that all the documentation only exists on the computer, and if this is the case there are

two points to note: 1. How does the system cope with novice users? you cannot expect a novice user to begin by reading documentation off the computer 2. You still need to print out the documentation for the examiner. A possible template for the user guides has been included at the end of the section, but there are some basic rules: Never include a printout that does not have some annotation to go with it. Test the guides yourself to make sure that they work Make sure that someone other than yourself has tested the guide Are the guides standalone documents? they should not be an integral part of the project documentation but separate documents. The layout of the guide should be easy to follow and logical for example start with the main menu and cover all the options on a screen by screen basis, or you may choose to cover input, then processing, then output. The choice is yours but it must be easy to use. The various guides you should create are: Getting Started Guide User Guide Troubleshooting Guide On Line Help

Getting Started Guide This guide contains information for the basic user on how to start using the system. The guide should not begin from how to switch on the computer (believe it or not, some guides do!) but should start from the opening screen of the software package. The guide should contain a purpose of the software what is it to be used for? and where is it to be used?. It should include all the basic information required to use the system if a username and password are needed, where do they get them from etc. It should be written for the basic novice user. This means that there should be as few technical terms as possible and a glossary of terms used mouse, click etc. This guide will not be very long, no more than a few pages. It will contain, along with the glossary of terms, an index and a table of contents. User Guide This is the most important of all of the guides. The user guide contains all the information needed to run the system on a day-to-day basis. It should be remembered at all times that the audience of the document will range form novice to expert users. It needs to contain details on: Entering Data This will include the data needed to be entered into the system and where to enter it. This must be done by a selection of screenshots and annotation. Wherever possible, example of the actual data to be used should be included. If there is more than one data entry point, they need to be covered in separate sections.

Processing All options must be covered. Processing includes anything that happens to the data sorting, searching, updating, deleting, etc. If there are many options that cover a similar item, such as four different methods of searching, they can be grouped together. For processing, you need to cover every button/option. For example, on a form you may have a main menu with lots of buttons. Within the data form, there may be options to go to the first, last, next and previous records. All of these must be documented. However, if you have several forms with the same buttons on them, you only need to cover the buttons on one form, not all of them. Output There are likely to be three main methods of output screen output, disk output and hard copy (paper). Each of the different forms of output how to get them and what they will give must be covered by the documentation. Backup and recovery of data This will be covered by a simple set of screenshots and instructions showing how to backup and restore data. Security Different systems will required different security options and however your system has implemented the security needs to be discussed. The guide must contain an index, glossary of terms and a table of contents. It should be a standalone document. There are many different ways you can write a user guide. The ideal would be to look at a user guide produced by the major software providers, or a Dummies Guide for example, and see how it is laid out. No one is expecting you to produce something that is up to the same standard (although no one is going to stop you!). The criteria are that it needs to be usable and helpful. The sample below is a simple example of how you might lay out a user guide. It involves collecting all the images make sure that the images are: what the user will see no design screens have been cropped so there is no background have real data in them so the user can see what the are supposed to do Once you have collected the images, they must be positioned on the page in such a way as to allow arrows and explanatory text to be filled around them.

Sample Layout for User Guide This screen is for viewing and changing details about companies. You need to search through the companies by pressing the First, Next, Previous and Last buttons, until you come to the name and address of the company you want. When you begin, some of the buttons will be greyed out. In the screen below the First and Previous buttons are greyed out. This is because this is the first record and there is nothing before it. If you moved to the next record, the greyed out buttons would become active (the text turns black and you can click on them) You can then edit the details and press the Update button to save your changes. If you want to exit out of the screen, press the Close button.

Number in the database Company name

Company Address Buttons

Figure 4.6 Troubleshooting Guide This is a guide to problems and solutions. The troubleshooting guide needs to list all the different problems the user might encounter, what caused them and how to get out of them. Any error messages the system generates must be included (if you have used the recommended format for error messages, with each message represented by a unique number, they errors can be sorted and presented by number) The troubleshooting guide is a collection of screenshots of the errors and text about the error. As with the other guides, there must be an index, a glossary of terms and a table of contents. In general terms, anything that generates an error message in your testing should be included in the troubleshooting guide. On Line Help This is help that you will need to printout as you are not allowed to submit disks. The on line help will depend on the package you are using. It could be web based help using HTML, or a collection of tooltips, or a series of text files accessed by a button click. On line help must be accessible and relevant. Usually it is not long but a collection of short sharp

documents. The contents will depend on the individual requirements, but if required you should again include table of contents, glossary and index.

Headings to be used for Section 4


There are no headings for Section 4 within the project as all the guides are standalone documents. The headings given below are those that should be included in the various guides. All guides should contain a table of contents, index and glossary of terms. Technical Documentation Hardware and Software Specification Backup and Recovery Technical Procedures Data Structures (data models, relationship diagrams) Data Flow Diagram Input Documents/Screens Output Documents/Screens Annotated Code Listing (inc formulae) Data Dictionary Security of the System Error Messages User Documentation Getting Started Guide User Guide Input Processing Output Backup and Restore Security Troubleshooting Guide On Line Help

Evaluation
This is the final section of the project. By reading the first section the analysis, and the final section, a moderator can get a good idea of what you have done and how successful you have been. They can tell the quality of the project and how much attention they need to pay to the rest of the project. If the first and last sections are good, then they will look at the middle sections, but only to confirm to marks given by the teacher. If they are not good, hard to follow and difficult to understand, then, in order to understand the project and what is going on, they will have to read the rest of it in detail.

Overview of Section
The evaluation of the project is a twofold exercise it needs to be done by you and by the end user. Your evaluation needs to tie in with the objectives given in the Analysis section (so without a good analysis, with objectives, you will not score any marks in the evaluation) and with the error log you have kept throughout the project. The evaluation by the end user requires any individuals identified earlier in the project (analysis) to be present and to have looked at the system and given a written response.

With the evaluation, it is not about how well you think you have done, how much fun you have had or what you have enjoyed doing or disliked doing. In fact, the evaluation is nothing to do with you, but to do with what the finished product you have created can and cannot do. Honesty is the best policy with any evaluation, if something has not worked then say so and explain why and what you have done about it. If you try to cover it up, the likelihood is that in the rest of your project the evidence will be there to prove that it has not worked and you will be caught out lying. If you have lied here, how can the examiner then be sure you have not lied elsewhere?

Discussion of the degree of success in meeting the original objectives


It is not possible to achieve marks in this section unless you have completed the requirements specification earlier in the project. To complete this you need to take each objective listed in the requirements specification and discuss the degree of success you have had in meeting it. What does it mean - degree of success? There are four possibilities: 1. the objective has been met completely 2. the objective has not been met in its entirety, but most of it has been 3. the objective has only partially been met 4. the objective has not been met at all Initially, this can be done in the form of a table. This will give the examiner an immediate overview of how successful you have been in implementing the requirements specification. In your finished table, you will of course need to list the objectives rather than referencing them. Anything you can do to stop the examiner flicking backwards and forwards though the project should be done, even if it means repeating yourself many times.

Format for Visual Reference for Meeting Objective Completely Met Objective 1 Objective 2 Objective 3 Objective 4 Mostly Met Partially Met Not Met Page No of Evidence 65 66


Figure 5.1

65 67

You should only place one mark in each box. If necessary, and for this it would need to be filled in by hand, it might be appropriate to place a mark across two boxes, or to one end of a box, for example with objective 2, it has only been partially met, but by placing it towards the left hand side of the box I am showing that it is almost into the mostly met box but not quite.

The table is only an initial guide - on its own it will not get you any marks. To get marks, with each objective, you must decide into which of the four statements listed above the objective falls. You must back up the objective with evidence. The evidence may be from testing, it may be a statement from the end user, or a printout of parts of the development. Every objective must be covered, discussed and evidence produced to back it up. If you miss out any of them, you will lose marks. It is not important whether you meet all of the objectives. You can still achieve full marks even if you have not managed to complete the objectives. This section is a full and frank discussion of the success of the project. Where you have not completed the objectives, you must provide a reasoned discussion as to why it has not been met, what you have done to try and meet it and what you could do in the future to meet it. It should be possible to tie up problems you have had meeting the objective with the error log you are required to keep. It requires more than statements alone, in order to achieve the marks you must provide evidence. The more honest you can be, the better! The evidence you need to produce can be page references to test run printouts, or to specific areas of coding. If the objective you are producing evidence for is to do with the ease of use for different levels of users, it might be appropriate to get a written statement from the different users. If you have completed the full test plan in the development and testing section you will have gone through the design specification and given screenshots to show that each one has been implemented and works. The page references will direct the moderator to this section where the evidence of success can be found. Sometimes the evidence might not be in the project, you might have to go out and get it. This may require additional data collection, interviews or signed statements.

Evaluate the Users Response to the System


The marks in this section are awarded for three areas: 1. producing a user friendly system 2. user acceptance of the system 3. no known faults in the system Producing a User Friendly System All through your ICT lessons, you have probably been told to avoid such terms as user friendly, easy to use etc, and here now, in the mark scheme you are being asked to evaluate whether you have created a system that is user friendly. How do you know if a system is user friendly? The standard used in the mark scheme for deciding if an interface is user friendly is based on the comments of the end user. There are certain targets that are to be assessed by the end user and based on their response you will be awarded marks. This can be done through the use of a questionnaire. Part of a sample questionnaire might be:

Sample Questionnaire to evaluate User Friendly System Question Can you read the labels on the buttons? Is the colour scheme appropriate? Can you find all the options? Is the help easy to find? Is the help easy to understand? Can you enter data quickly? Can you enter data accurately? Yes No Comment


Figure 5.2

Once I found them the first time Yes if I use the glossary The error checking works well

Dont forget that you need to name and date every questionnaire. Include one blank and one filled in questionnaire in the body of the project and if you have more, then put the rest in the appendices. You can summarise the results of the rest using graphs in the body. If there are any No responses, you need to collect more information and evaluate what has gone wrong. If it is something simple then correct it, if it is a fundamental problem, then evaluate and discuss it. You need to make sure that 90% of the responses are Yes. The user is someone who knows and understands the underlying system they know about the data and the results required, but may not necessarily be competent at using computers. You need to assess whether they can use the system, understand the screens, enter the required data and produce the results they want in a format understandable to them.

Once you have the results of the users evaluation of the system, you must discuss them and draw conclusions about the user friendliness of your system. These need to include such items as: Clarity of menus Clear on screen help (labels, instructions, tool tips) Easy methods of inputting data (drop down boxes, radio buttons) No dead ends in the system Options easy to find Number of clicks to target If the user does not agree that the system in some parts, is user friendly, take on board the comments, redesign and retest showing what you have done and the new results. This is perfectly acceptable. Do not try and fake the results. User Acceptance of the System The user must accept the system. By the user, it means the people who have originally commissioned you to write the project. There is a sample acceptance letter in the Development Testing and Implementation Section. The same letter (if the layout has been followed) can be used for both sections. It may be worth duplicating the letter as it avoids confusion. The acceptance letter should be a formal letter, containing both the name and address of the organisation and your name and address (which could be the schools), the date, a reference to the project title and a formal date on which the project will be accepted and all responsibility for the project becomes the property of the organisation. The letter should refer to the objectives (which were agreed with the organisation and signed off by them) and to the faults in the system. If there are faults, the date of acceptance may be extended to solve the problems. If there are faults, they should be specified in the letter. The letter should also refer to the user friendliness of the system. Overall the letter is something that will be referenced throughout the evaluation. It can be used in the first section to show user satisfaction with the objectives, it can be used to show user friendliness, acceptance of the system and in the final section, it can be used to mention good and bad points, limitations and desirable extensions. No Known Faults in the System It is not necessary to eliminate all the faults in the system. If there are some, then you will not be able to achieve the full 5 marks in this section, but only a maximum of 3. In the acceptance letter (the same letter that is displayed in the Software, Development, Testing and Implementation section) the user needs to either state that there are no known faults with the system, or to say that there are and to list them. If there are none, then a reference to the letter is all that is required in this section. If there are faults, you can do one of two things. You can accept that there are faults and do nothing, meaning that you can only achieve a maximum of 3 marks, or you can correct the faults, retest and get a second letter with the comments of no faults included. If you choose this second option, there is a fault record log which you can fill in. If there are faults, it is not in your interest to either ignore them and fake the letter or to correct

them without documenting the process.

Desirable Extensions
There are four marks available for this section and the title is not really applicable to most of the content! There are three areas you must cover to gain marks in this section: 1. identify good and bad points of the system 2. highlight limitations of the system 3. describe necessary extensions to the system and how they should be carried out Identify Good and Bad Points The good points and bad points about the system is not a list of what you think or like. It is a discussion of a combination of the users views, testing and evaluation against the original objectives. You should be identifying and describing the good and bad points of the final system the one that is to be installed in the end users workplace. If possible you need to be covering such aspects as the speed of loading, the searching, user interface, file handling, editing, adding and deleting facilities etc. You might even want to describe some of the programming perhaps a particular procedure is good for example, entering the postcode and returning the street, town and county. You must not only concentrate on the success and good points. It should also cover bad points about the system this might include such things as the screen design and size, menus and short cut keys no having sensible letters etc. To get the marks the examiner will be looking for a considerable described list perhaps fifteen or more and each item has some discussion with it, and most importantly, honesty. Limitations of the System There will always be something that the system will not do that it should. This section is about describing those limitations. What can the system not do these are likely to be those objectives that have not been completely implemented. In some ways this section is difficult to do. If you have a perfectly programmed project it is not likely to have any limitations, so how can you complete this section? The true answer is that any system, no matter how good it is, will always have limitations. The number of limitations will depend on the complexity of the system. If you have chosen a relatively simple project then the solution will be simple and you will be able to cover most of the requirements. In this case, you are unlikely to be able to achieve the marks because of the simple nature of the project.

Limitations of a Fuel Haulage System Take a project about working out fuel expenses for a haulage company, what you will find is that the limitations will overlap with desirable extensions for example does it work out expenses based on gallons and litres, does it handle European currency, does it attach expenses to a database of employees, can I search the database using any field and parts of fields? Any of these may be a combination of limitations and extensions.

Figure 5.3 To complete this section you need imagination! (but please, not too much) Necessary Extensions As stated above, this section is likely to be a continuation of the limitations of the system what it cannot do now is probably something that you would want it to do in the future. You must not only describe the possible extensions but give some idea as to how to carry them out. This does not need to be a complete design, but a very general rough description of what might be done to implement the extension. In the acceptance letter from the previous section, it may be that the management/user has specified some good and bad points, limitations and desirable extensions. (If they have not, then it might be appropriate to get a letter form them which does so.) If you identify the good and bad points, limitations and extensions but do not describe them, then you will not achieve full marks, but 3 out of 4. If you identify good and bad points, limitations but no extensions, then you will only get 2 and of you include mostly good points and only one or two bad points and limitations, then 1 mark is all you will receive.

Headings to be used for Section 5


The following headings are recommended to ensure that you have covered all of the required elements. To get full marls in this section, you must have covered all of these headings, they are not optional. (although some of the sub headings are, such as the table) Discussion of Degree of Success in Meeting Original Objectives Table of Success Discussion of Objectives Evaluation of Users Response to the System User Friendly System User Responses Evaluation of Responses User Acceptance No Known Faults Desirable Extensions Good and Bad Points of the System Limitations of the System Possible Extension

Das könnte Ihnen auch gefallen