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

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. 3651A Create User & Technical Documentation

3651A Create User & Technical Documentation 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. 3651A Create User & Technical Documentation

3651A Create User & Technical Documentation

3651A Create User & Technical Documentation planning drafting reviewing testing producing distributing updating. Planning 3651A Create User & Technical Documentation

3651A Create User & Technical Documentation 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: create a document library blueprint determine the resources required develop a schedule determine the budget 3651A Create User & Technical Documentation

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. 3651A Create User & Technical Documentation

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

3651A Create User & Technical Documentation 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. 3651A Create User & Technical Documentation

3651A Create User & Technical Documentation 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. 3651A Create User & Technical Documentation

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. 3651A Create User & Technical Documentation

3651A Create User & Technical Documentation

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. 3651A Create User & Technical Documentation

3651A Create User & Technical Documentation 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. 3651A Create User & Technical Documentation

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

3651A Create User & Technical Documentation The people who have been identified as reviewers in the specification, such as the technical editor, undertake the review. In response to the reviewer’s 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. 3651A Create User & Technical Documentation

3651A Create User & Technical Documentation 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. 3651A Create User & Technical Documentation

3651A Create User & Technical Documentation 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. 3651A Create User & Technical Documentation

3651A Create User & Technical Documentation 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. 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. 3651A Create User & Technical Documentation

3651A Create User & Technical Documentation 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. The documentation must reflect the changes in the computer system. 3651A Create User & Technical Documentation

3651A Create User & Technical Documentation 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 3651A Create User & Technical Documentation

3651A Create User & Technical Documentation Summary 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. 3651A Create User & Technical Documentation

3651A Create User & Technical Documentation 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. 3651A Create User & Technical Documentation

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. 3651A Create User & Technical Documentation

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 how to install or set it up how to operate it what to do, or who to call, if it doesn’t work. 3651A Create User & Technical Documentation

3651A Create User & Technical Documentation 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. 3651A Create User & Technical Documentation

3651A Create User & Technical Documentation 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. Documentation is often found on an organisation’s intranet. It is not uncommon to find policies and procedures and computer system documentation on the intranet, rather than in printed form. 3651A Create User & Technical Documentation

3651A Create User & Technical Documentation 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 can now be produced in HTML format using Microsoft’s HTML Help. These help files can be viewed by Internet browsers such as Internet Explorer and Netscape. 3651A Create User & Technical Documentation

3651A Create User & Technical Documentation 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. 3651A Create User & Technical Documentation

3651A Create User & Technical Documentation 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. 3651A Create User & Technical Documentation

3651A Create User & Technical Documentation 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. 3651A Create User & Technical Documentation

3651A Create User & Technical Documentation 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. 3651A Create User & Technical Documentation Activity 1.1