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

2. 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

3. 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

4. 3651A Create User & Technical Documentation

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

6. 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

7. 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

8. 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

9. 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

10. 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

11. 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

12. 3651A Create User & Technical Documentation

13. 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

14. 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

15. 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

16. 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

17. 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

18. 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

19. 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

20. 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

21. 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

22. 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

23. 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

24. 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

25. 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

26. 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

27. 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

28. 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

29. 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

30. 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

31. 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

32. 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