IT-project (10-20 ECTS) is a part of advanced studies in Computer Science (CS). The aim of IT-project is to familiarize the student in assessing a task larger than the assignments given in courses on the lower levels of studies.
IT-project is a more practical work than e.g. master's thesis. While master's thesis in most cases means an analysis of the subject according to litterature or an empirical study, IT-project deals with practical assignment such as implementation of a tool. IT-project and thesis often deal with the same subject, but it is not a rule.
These instructions apply best with documenting an IT-project that consists mainly of producing software. In case of a totally different IT-project, the student must agree on the form of documentation with the supervisor.
Working on an IT-project requires concentrated work, and international students usually work full time. The IT-project is often a part of the department's research, and any delays in the IT-project hampers the work of other members of the research group. Projects that are implemented in industry are subjects to scheduling within the company. Typically, the duration of a project is between three to six months. The 20 ECTS credit load corresponds to approximately 16 weeks of full time work.
Characteristically, a continuous contact must be maintained between the student and the supervisor. Once a month (or according to a schedule approved by the supervisor) a written or oral report must be presented by the student. The report consists of a log of tasks and time spent on each task during the reporting period. Also a plan for the next reporting period must be included. In addition to the report meetings, the progress of student's work is monitored by presentations in a group.
At the beginning of the IT-project, the student writes a definition of requirements, which is left for the supervisor for approval. This definition of the work needs not be strictly testable for its every part, but at least outlines the critical points of the system, i.e. those elements of the project that must be especially paid attention to. In some cases the more exact content of the IT-project is formed only during the course of the work. Also then the definition of requirements must be done, in order to have a common impression between the student and the supervisor on the work content.
Documentation is a compulsory part of the project.
The grade given for the IT-project depends both on the quality of the work and the documentation, as well as the working habits and activity of the student.
Formatting of the code
A consistent practice must be maintained in the formatting of the code.
Comments should be numerous. At the definition of each variable, a legend of the meaning must be presented. Descriptions of functions and procedures must be included in the code, preceding the rest of the code.
Information content and a clear presentation are essential in the documentation. The style or formatting is of less importance. Certainly a good style is not a disadvantage, but it does not prominently affect the grading. The system built in the IT-project is meant to be maintained. Thus the documents are subject to change, and it is not reasonable to produce the documents using a system that might not be available by the maintainers. The tool for producing the documents must be agreed with the supervisor.
The documentation of the IT-project normally consists of three parts, that are entirely separate of each other:
- User manual
- Component description
Each of the parts has a separate title page, table of content etc. The three parts have separate audiences, and they may not contain references to each other. In case of the Component description, the reader is assumed to have the User Description at hand, and the User manual need not be repeated in the Component Description. In other cases, the repetition of general parts of the documents is allowed and is even encouraged.
All three documents must be submitted in hardcopy. Even when the User manual is available in a computer readable form, a proper hardcopy is needed (not only a pile of separate pages printed). At least an elementary manual must be produced, written as to a person starting to familiarize the system. In addition, the computer readable materials must be provided as a printout (to make it easier to inspect and grade the work).
The Advertisement is a one-page description of the system. It shoud be made in such a way that after formatting it could be published in an IT-magazine. The Advertisement shortly describes the purpose of the system, its essential features, advantages over competitor products, usage environment, and hardware and software requirements. The Advertisement must be positively attentive, but truthful. When writing the Advertisement, bear in mind that the reader may have no prescription of the purpose and usefulness of the system.
User manual is intended for the normal user of the system. The user should be able to use the parts included in the system, and understand the connection between the system and the user's actual tasks. The User manual can principally be constructed in two ways: an elementary tutorial, or a manual listing all features in detail.
The manual must contain good resources to retrieve information. For example the table of contents must be descriptive. It may mimic the system main menus, or advance according the user's working process. A long user manual is not necessarily easy to use. Sometimes the lowest level subtitles can be excluded. A good feature at the end of the manual is a word index, with references to all the pages containing a specific word.
The manual starts with a reasonable description of the usage environment and the purpose of the system, continues with the actual User Manual and ends with instructions for installing the system. The Istallation Manual must be written for a person that has all source files on a media, and is able to copy the files in some directory of his own. Therefore, no references may be made in the manual to any certain computer or directory, where the files should be retrieved.
The User manual must contain an alphabetic list of error messages. In addition to the message text, all procedures that were performed by the system when displaying the message, must be explained. The direct reason for displaying the message must be given (normally evident from the message itself), also the usual indirect conditions leading to the error situation. The different recover actions must be listed.
Use of passive voice should be avoided. For example the expression "New data is written on screen" does not hint the user whether the work is to be done by the computer or the user himself. The user can be instructed like "Give the file name, and the program lists the file on screen."
Component description must be done as if the reader was a student of the same level, who is about to make a change to the code and even continue on the project. New ideas for the changes should be possible to realize, and the relevant code positions easily found. It is essential that the general structure of the programme is described, and the most important solutions are explained. Simple details can be omitted. If some unconventional tools are used, the description must be more accurate.
Requirements specifications and the planning documents possibly produced during the work, whose contents do not naturally fit in the Component description, are attached to the Component description.
The Component description must contain at least the following parts:
- The purpose: to which subject area the system belongs; in which tasks the system may be of help; what is supposed to be done with the system.
- The working principles: general principles the system's operation; names of the special algorithms used or general level descriptions of those; principles of unconventional use of files; other systems linked to the present system; parts of the system completed (or partly completed) elsewhere.
- Division of the system in its primary units: separate programs and their interconnections; main components of separate programs; present here a scheme with 5-10 parts and their connections.
- Data structures: the most important data structures and the principles of their use; the most important variables and their purpose; example of the content of the database, preferably as a picture.
- Module descriptions: the purpose of the module and their principles of operation; a list of functions and a description of their call relations; a description of each function and procedure must be included in the program code preceding the code of the finction or procedure itself - these can be omitted from the Component description.
- Changes in the system: the features easily changeable, and directions to make those changes (e.g. valid ranges for changeable constants); a list of features changeable with a moderate amount of work, and a list of features changing of which reguire rebuilding the whole system.
- Instructions for system management: directories and files; version update; compilation.
- Testing: required scope of the department test; description of test case directory; directions of running the test cases; reasons for realization of the test coverage; the same for integration testing.
Planning of test cases must be based on some coverage principle (e.g. 95 % coverage for the program code, and each test getting at least once its individual possibility to provide a result). A set of test cases must be formed on this basis, each having the required coverage. Completion of the test coverage must be described in such a detail that the reader is convinced on its adequacy. Test procedure and the comparison of test result to excpected results must be automatized as far as possible.