3651a create user & technical documentation 1 3. technical documentation

3651A Create User & Technical D3651A Create User & Technical Documentationocumentation

11

3. Technical 3. Technical DocumentationDocumentation


22

What is technical What is technical documentation?documentation?

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


33

Developing Technical Developing Technical DocumentationDocumentation

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


44

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


55

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


66

system requirementssystem requirementssystem flow chartsystem flow chartdata flow diagramdata flow diagramdata dictionarydata dictionaryuser interfaceuser interfacemaintenance history maintenance history log book.log book.


77

System requirementsSystem requirements

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


88

System flow chartSystem flow chart

The system flow chart is a diagram of The system flow chart is a diagram of consecutive steps showing how the consecutive steps showing how the complete system will behave. This is complete system will behave. This is achieved by indicating each of the achieved by indicating each of the following:following:

the processesthe processes inputs and outputs of datainputs and outputs of data where the input comes from (sources)where the input comes from (sources) where the output goes to (destinations).where the output goes to (destinations).


99

Inputs and outputsInputs and outputs

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


1010


1111


1212

Processing flowsProcessing flows

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


1313

Drawing the system flow Drawing the system flow chartchart

The system flow chart indicates how the The system flow chart indicates how the processing is done. It indicates a sequence of processing is done. It indicates a sequence of processing and whether computers are used or processing and whether computers are used or the data is processed manually. The following the data is processed manually. The following guidelines will help you draw a system flow chart.guidelines will help you draw a system flow chart.

Look for the major processes that cover all the Look for the major processes that cover all the system activities.system activities.

Draw the processes in the order in which they Draw the processes in the order in which they occur.occur.

Identify and draw the inputs and outputs.Identify and draw the inputs and outputs. Indicate the media for the sources and Indicate the media for the sources and

destinations of data.destinations of data. The system flow chart for the Gawler Little The system flow chart for the Gawler Little

Athletics cross country system is shown in figure Athletics cross country system is shown in figure 2.4.2.4.


1414


1515

Data dictionaryData dictionary

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


1616

User interfaceUser interface

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

standards for and samples of screen designs or layoutsstandards for and samples of screen designs or layouts standards for and samples of report designs or layouts.standards for and samples of report designs or layouts.


1717

Maintenance history log Maintenance history log bookbook

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


1818


1919

Other Technical Other Technical DocumentationDocumentation

There are many other forms of There are many other forms of technical documentation. Skills in technical documentation. Skills in those particular areas are required to those particular areas are required to produce that documentation. Object-produce that documentation. Object-orientated system development is one orientated system development is one such area such area


2020

ReferencingReferencing

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

version numbers.version numbers.


2121

Version numberVersion number

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


2222

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

Activity 2.4


2323

SummarySummary Technical documentation for computer systems Technical documentation for computer systems

covers a wide field, and includes that of software covers a wide field, and includes that of software applications. Many different techniques can be applications. Many different techniques can be used to produce documentation. Which technique used to produce documentation. Which technique is used depends on the method ology. Some of the is used depends on the method ology. Some of the documentation produced includes the following:documentation produced includes the following:

system requirementssystem requirements system flow chartsystem flow chart data flow diagramdata flow diagram structured Englishstructured English data dictionarydata dictionary user interfaceuser interface maintenance history log book.maintenance history log book.


2424

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

3651a create user & technical documentation 1 3. technical documentation

Documents

technical documentation

computer system

user technical documentation3

user technical documentation4

user technical documentation2

user technical documentation5

online documentation

complete system