Presentation is loading. Please wait.

Presentation is loading. Please wait.

3651A Create User & Technical Documentation 1 2. Process in Producing Technical and User Documentation.

Similar presentations


Presentation on theme: "3651A Create User & Technical Documentation 1 2. Process in Producing Technical and User Documentation."— Presentation transcript:

1 3651A Create User & Technical Documentation 1 2. Process in Producing Technical and User Documentation

2 3651A Create User & Technical Documentation2 Methods for Producing Documentation A widely accepted methodology for developing computer system documentation is the standard documentation process. The starting point in this process is the document library blueprint this is a description of the different types of documentation required (such as training manual, procedure manual, online help). It is a specification of the documentation to be produced.

3 3651A Create User & Technical Documentation3 Individual document blueprints are specified after the document library blue print has been approved. These individual specifications are more than an outline. They identify the context of the document, its purpose and the detailed content. Figure 1.11 shows the stages and their sequence in the standard documentation process. Individual document blueprints are specified after the document library blue print has been approved. These individual specifications are more than an outline. They identify the context of the document, its purpose and the detailed content. Figure 1.11 shows the stages and their sequence in the standard documentation process.

4 3651A Create User & Technical Documentation4

5 5 planning planning drafting drafting reviewing reviewing testing testing producing producing distributing distributing updating. updating. Planning Planning

6 3651A Create User & Technical Documentation6 Planning As in other disciplines such as constructing a building or developing software, planning is essential. Just as a builder would not start building a house without a schedule, specification and budget, you should not start writing the documentation without plan- fling first. As part of the planning process, you need to: As in other disciplines such as constructing a building or developing software, planning is essential. Just as a builder would not start building a house without a schedule, specification and budget, you should not start writing the documentation without plan- fling first. As part of the planning process, you need to: create a document library blueprint create a document library blueprint determine the resources required determine the resources required develop a schedule develop a schedule determine the budget determine the budget

7 3651A Create User & Technical Documentation7 Creating a document library blueprint Creating the document library blueprint involves identify all the pieces of documentation and how they are related, and developing a specification for each known as the document specification. The document library blueprint and specifications provide the information the authors need to produce the documentation.

8 3651A Create User & Technical Documentation8 The individual document specification covers the documents: I purpose I audience I audience characteristics characteristics needs needs diversity diversity related documents related documents media media production plan production plan reviewing and testing reviewing and testing update plan. update plan.

9 3651A Create User & Technical Documentation9 Purpose The purpose of the document is to define the technical problem being addressed in the context of the business environment. This may be addressed in the form of objectives for the documentation.

10 3651A Create User & Technical Documentation10 Intended reader The intended reader or user must be identified. Their background and any other relevant factors related to their use of the computer system must be stated. Factors such as language, culture, attitudes and environment may be important. The characteristics of the reader are often described in the final documentation. The intended reader or user must be identified. Their background and any other relevant factors related to their use of the computer system must be stated. Factors such as language, culture, attitudes and environment may be important. The characteristics of the reader are often described in the final documentation.

11 3651A Create User & Technical Documentation11 Developing the schedule A schedule lists the tasks to be undertaken to produce the documentation, and the order in which they need to be done. A framework for the tasks is provided by the methodology. You may divide the tasks further so that you can monitor the progress of the writing project, and allocate jobs to individual people. Estimate how long each task will take so that you can specify the start and finish dates. Table 1.1 is an example of a schedule. A schedule lists the tasks to be undertaken to produce the documentation, and the order in which they need to be done. A framework for the tasks is provided by the methodology. You may divide the tasks further so that you can monitor the progress of the writing project, and allocate jobs to individual people. Estimate how long each task will take so that you can specify the start and finish dates. Table 1.1 is an example of a schedule.

12 3651A Create User & Technical Documentation12

13 3651A Create User & Technical Documentation13 Determining the budget The budget allocation and the breakdown of items of expenditure need to be detailed. The cost of user documentation, as part of the development budget, generally varies from 10 to 20%. The cost of production of paper-based documentation varies from one to eight pages per person per day. The variation will depend on the complexity of the documentation and the methodology and technology used to produce it. For example, a 100-page manual can take 25 days for one person to produce. At a daily cost of $200 the final production cost would be around $5000. The budget allocation and the breakdown of items of expenditure need to be detailed. The cost of user documentation, as part of the development budget, generally varies from 10 to 20%. The cost of production of paper-based documentation varies from one to eight pages per person per day. The variation will depend on the complexity of the documentation and the methodology and technology used to produce it. For example, a 100-page manual can take 25 days for one person to produce. At a daily cost of $200 the final production cost would be around $5000.

14 3651A Create User & Technical Documentation14 Drafting Drafting involves creating the documentation, whether printed or online. The person (or people) with knowledge about the subject area (that is, the computer system) writes the content. There may be several passes at writing the documentation, depending on the review and testing that occurs.

15 3651A Create User & Technical Documentation15 Reviewing Purpose are the objectives as stated in the document specification being met? Content Content Is the subject area covered adequately? Is the subject area covered adequately? Are there any omissions? Are there any omissions? Is there any unnecessary detail? Is there any unnecessary detail? Are there errors? Are there errors? Is the content appropriate for the user? Is the content appropriate for the user? Grammar is there spelling or grammatical errors? Grammar is there spelling or grammatical errors? Clarity is the material explained clearly? Clarity is the material explained clearly? Style is the writing style appropriate for the intended user? Style is the writing style appropriate for the intended user?

16 3651A Create User & Technical Documentation16 The people who have been identified as reviewers in the specification, such as the technical editor, undertake the review. In response to the reviewers comments, the document is corrected by the writer (s) and reviewed again. This process continues until the errors or omissions have been corrected. Usually this involves one or two redrafts. The people who have been identified as reviewers in the specification, such as the technical editor, undertake the review. In response to the reviewers comments, the document is corrected by the writer (s) and reviewed again. This process continues until the errors or omissions have been corrected. Usually this involves one or two redrafts.

17 3651A Create User & Technical Documentation17 Testing The documentation is tested by people who represent the users of the documentation. For a software application, testing involves using the documentation in conjunction with the software. The documentation is tested by people who represent the users of the documentation. For a software application, testing involves using the documentation in conjunction with the software.

18 3651A Create User & Technical Documentation18 Production When the documentation has been satisfactorily completed, it is ready to be produced. As with any product development, approval should be obtained before production begins. The approval or sign-off is obtained from the project manager, the person who is managing the development of the computer system. The project manager will consult the documentation developers, reviewers and testers to ensure that the documentation is ready to be released. When the documentation has been satisfactorily completed, it is ready to be produced. As with any product development, approval should be obtained before production begins. The approval or sign-off is obtained from the project manager, the person who is managing the development of the computer system. The project manager will consult the documentation developers, reviewers and testers to ensure that the documentation is ready to be released.

19 3651A Create User & Technical Documentation19 Distribution Distributing the documentation means making it available to the users of the computer system for which it was designed. The documentation needs to be available at the time of packaging. The documentation needs to be available at the time of packaging. Similarly with online documentation. If a CD is to accompany the product release, whether hardware or software, it must be pressed and ready. If online help is to be present with a software application, it must be incorporated into the software. Similarly with online documentation. If a CD is to accompany the product release, whether hardware or software, it must be pressed and ready. If online help is to be present with a software application, it must be incorporated into the software.

20 3651A Create User & Technical Documentation20 Updating Computer systems, both hardware and software, are never static. Change is inevitable as technology advances and user requirements change. New models of hardware and new versions of software applications are continually being developed and released. Computer systems, both hardware and software, are never static. Change is inevitable as technology advances and user requirements change. New models of hardware and new versions of software applications are continually being developed and released. The documentation must reflect the changes in the computer system. The documentation must reflect the changes in the computer system.

21 3651A Create User & Technical Documentation21 Version control It is possible that there will be different versions of documentation referring to different versions of a software package these versions should be clearly distinguished. Both the name of the document and the version should be indicated. Sometimes the name of the document will indicate the version for example, Microsoft Office 2000 distinguishes that version of documentation from Microsoft Office XP. If the version is not distinguishable by the title, you can indicate the version by using a version number (or edition number), and the date on which the documentation is published. Activity 1.3

22 3651A Create User & Technical Documentation22Summary The prime purpose of documentation is communication. In information technology it provides information to people who are developing, maintaining or using computer systems. There are two broad categories of computer system documentation: technical and user. Technical documentation is for the people who develop or maintain computer systems; user documentation is for those who use the computer system for a purpose. Documentation can be in printed or online form, or both.

23 3651A Create User & Technical Documentation23 There is a standard documentation process for producing documentation. The methodology of plan, draft, review, test, produce, distributes and update is a simple but effective method of developing documentation. Standards for producing documentation help ensure quality and consistency. Standards can originate: at the industry level, such as from the Standards Australia organisation; from the organisation, which may have its own standards; and from within the project of developing or maintaining the computer system. Templates are specific tools used to help documentation developers follow a standard layout.

24 3651A Create User & Technical Documentation24 Media for documentation The two main forms of media for user and technical documentation are paper and online. They perform in different ways, but have a common purpose. The choice of medium is determined by many factors. The most important is usability how well the documentation helps users of the application.

25 3651A Create User & Technical Documentation25 Paper-based documentation Paper documentation is also referred to as print media, and includes manuals, reference guides and brochures (covering a variety of appliances, tools and toys as well as computer hardware and software). the features or functions of the equipment or software application the features or functions of the equipment or software application how to install or set it up how to install or set it up how to operate it how to operate it what to do, or who to call, if it doesnt work. what to do, or who to call, if it doesnt work.

26 3651A Create User & Technical Documentation26 Online documentation Online media use the computer technology itself to deliver the documentation. The most familiar examples are messages to the user and online help. Figure 1.6 shows an example of online help. Online media use the computer technology itself to deliver the documentation. The most familiar examples are messages to the user and online help. Figure 1.6 shows an example of online help.

27 3651A Create User & Technical Documentation27 Internet/lntranet The Internet has become a rich source of information, including computing systems documentation. Information about all types of hardware and soft ware can be found. Some information comes from the suppliers, although much of it is from other parties. The Internet has become a rich source of information, including computing systems documentation. Information about all types of hardware and soft ware can be found. Some information comes from the suppliers, although much of it is from other parties. Documentation is often found on an organisations intranet. It is not uncommon to find policies and procedures and computer system documentation on the intranet, rather than in printed form. Documentation is often found on an organisations intranet. It is not uncommon to find policies and procedures and computer system documentation on the intranet, rather than in printed form.

28 3651A Create User & Technical Documentation28 Help files Help files are common in many applications, reflecting the increasing popularity of online documentation. Help files often provide detailed and structured information so that the user can find what they want without the inconvenience of a bulky manual. Help files are common in many applications, reflecting the increasing popularity of online documentation. Help files often provide detailed and structured information so that the user can find what they want without the inconvenience of a bulky manual. Help files can now be produced in HTML format using Microsofts HTML Help. These help files can be viewed by Internet browsers such as Internet Explorer and Netscape. Help files can now be produced in HTML format using Microsofts HTML Help. These help files can be viewed by Internet browsers such as Internet Explorer and Netscape.

29 3651A Create User & Technical Documentation29 Hypertext Hypertext is a common online technique in which information appears about the word or picture being pointed to with the mouse. These spots on the screen are sometimes called hotspots. Hypertext is a common online technique in which information appears about the word or picture being pointed to with the mouse. These spots on the screen are sometimes called hotspots.

30 3651A Create User & Technical Documentation30 Wizards Wizards are another form of online documentation, in which instructions are presented on screen for the user to follow. The software automatically does common tasks by using the information the user provides in following the instructions. As an Excel Chart Wizard guides the user through the process of creating charts using the information already inserted by the user. As an Excel Chart Wizard guides the user through the process of creating charts using the information already inserted by the user.

31 3651A Create User & Technical Documentation31 Multimedia Text, graphics, video, animation, sound and interactivity can be integrated into online documentation this is known as multimedia documentation because it uses a range of communication media. Information can also be organised as a database this allows selected information to be retrieved quickly and accurately, making online media dynamic and powerful. Text, graphics, video, animation, sound and interactivity can be integrated into online documentation this is known as multimedia documentation because it uses a range of communication media. Information can also be organised as a database this allows selected information to be retrieved quickly and accurately, making online media dynamic and powerful.

32 3651A Create User & Technical Documentation32 CD-ROM CD-ROMs have recently overcome the storage limitations of online documentation and now provide the cheapest and most flexible way of providing documentation. Because of this, CD-ROMs are particularly useful for providing documentation that contains a large amount of information. Activity 1.1


Download ppt "3651A Create User & Technical Documentation 1 2. Process in Producing Technical and User Documentation."

Similar presentations


Ads by Google