3. Technical Documentation 3651A Create User & Technical Documentation

What is technical documentation? Technical documentation is the printed or online documentation that describes the construction of a computer system. A computer system can be the hardware (for example, the computer, a component of the computer such as a network card, or a peripheral device such as a printer), or the software application that runs on the computer (for example, a payroll system). People with engineering and writing skills develop hardware technical documentation. 3651A Create User & Technical Documentation

Developing Technical Documentation The documentation should be clear to the programmer. A builder constructing a house needs clear design specifications (that is, technical documentation) from the architect so that they can build the house as the client wants. 3651A Create User & Technical Documentation

3651A Create User & Technical Documentation The programmer will be familiar with the methodology, and therefore should understand the documentation. This will enable them to design and develop the software. The types of technical documentation that will be examined here are: 3651A Create User & Technical Documentation

3651A Create User & Technical Documentation The techniques vary according to the standards used, as defined in the systems development methodology. The programmer will be familiar with the methodology, and therefore should understand the documentation. This will enable them to design and develop the software. The types of technical documentation that will be examined here are: 3651A Create User & Technical Documentation

3651A Create User & Technical Documentation system requirements system flow chart data flow diagram data dictionary user interface maintenance history log book. 3651A Create User & Technical Documentation

3651A Create User & Technical Documentation System requirements The system requirements provide a description of the function of, and a list of key features or requirements of, the complete system in normal English. This is developed at the analysis stage and lists requirements of what the sys tem should be able to do, without specifying all the details of how to do it. In particular, any key requirements are highlighted here to ensure that they are not overlooked in the design stage. 3651A Create User & Technical Documentation

3651A Create User & Technical Documentation System flow chart The system flow chart is a diagram of consecutive steps showing how the complete system will behave. This is achieved by indicating each of the following: the processes inputs and outputs of data where the input comes from (sources) where the output goes to (destinations). 3651A Create User & Technical Documentation

3651A Create User & Technical Documentation Inputs and outputs Input refers to data that is accepted by a process. The process manipulates the data in some manner to produce an output. Table 2.2 shows the inputs and outputs for the processes of the cross country event system. 3651A Create User & Technical Documentation

3651A Create User & Technical Documentation

3651A Create User & Technical Documentation

3651A Create User & Technical Documentation Processing flows Some processes must occur in a certain order. For example, the event data must be collected before the event program can be printed. The flow of pro cesses and data is represented by a line with an arrowhead to indicate the sequence. 3651A Create User & Technical Documentation

Drawing the system flow chart The system flow chart indicates how the processing is done. It indicates a sequence of processing and whether computers are used or the data is processed manually. The following guidelines will help you draw a system flow chart. Look for the major processes that cover all the system activities. Draw the processes in the order in which they occur. Identify and draw the inputs and outputs. Indicate the media for the sources and destinations of data. The system flow chart for the Gawler Little Athletics cross country system is shown in figure 2.4. 3651A Create User & Technical Documentation

3651A Create User & Technical Documentation

3651A Create User & Technical Documentation Data dictionary The data dictionary gives a detailed description of the data in a system. It is built up over time by systems analysts and programmers. As a documentation task, you can start describing the data in the system. For example, the athlete’s name could be described as having a maximum of thirty characters, containing the first name, initial Of the middle name, and the last name. 3651A Create User & Technical Documentation

3651A Create User & Technical Documentation User interface In this part we are concerned with how the user and the system interact. The user has to get data into the computer in a way that should be easily accomplished, and needs to get data out of the system, using either a soft copy (a display on the screen) or a hard copy (printed report). In the area of the user interface there should be documentation on: standards for and samples of screen designs or layouts standards for and samples of report designs or layouts. 3651A Create User & Technical Documentation

Maintenance history log book Sometimes it may be useful to refer to changes to the system that have been made in the past. Perhaps you want to know what the change was, or why it was made. The maintenance history log book provides a permanent record of the changes. Figure 2.8 is an example of a maintenance history log book. 3651A Create User & Technical Documentation

3651A Create User & Technical Documentation

Other Technical Documentation There are many other forms of technical documentation. Skills in those particular areas are required to produce that documentation. Object-orientated system development is one such area 3651A Create User & Technical Documentation

3651A Create User & Technical Documentation Referencing Much effort goes into developing technical documentation over a period of time, and considerable documentation can accumulate. Unless the documentation has been referenced efficiently, it may take considerable effort to locate it. Or worse still, users might not even realise that it exists. The following technique will help to reference the documentation: version numbers. 3651A Create User & Technical Documentation

3651A Create User & Technical Documentation Version number Systems change over time. New releases of software have new features that users have requested. To manage the change, the software systems are given a version number. All documentation should have a version number that corresponds to the version number of the software, so that you know you have the correct version of the documentation. 3651A Create User & Technical Documentation

3651A Create User & Technical Documentation This requires that the version number be updated for each piece of documentation, even if there has been no change to it. After all, not every piece of documentation may change. However, it does force you to look at each piece of documentation, and make sure this is the case. If not, you need to update it. Activity 2.4 3651A Create User & Technical Documentation

3651A Create User & Technical Documentation Summary Technical documentation for computer systems covers a wide field, and includes that of software applications. Many different techniques can be used to produce documentation. Which technique is used depends on the method ology. Some of the documentation produced includes the following: system requirements system flow chart data flow diagram structured English data dictionary user interface maintenance history log book. 3651A Create User & Technical Documentation

3651A Create User & Technical Documentation Both text and diagrams are used to describe the system. Documentation is an important communication tool when developing a new system or maintaining an existing system. For example, a programmer can work more effectively on a system if documentation is available. The documentation must be kept up to date as the system changes. Having out-of-date documentation can be as damaging as having no documentation, as it may cause additional errors to be introduced into the software. 3651A Create User & Technical Documentation