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

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

11

2. Process in Producing 2. Process in Producing Technical and Technical and

User DocumentationUser Documentation


22

Methods for Producing Methods for Producing DocumentationDocumentation

A widely accepted methodology for A widely accepted methodology for developing computer system developing computer system documentation is the standard documentation is the standard documentation process. The starting point documentation process. The starting point in this process is the document library in this process is the document library blueprint — this is a description of the blueprint — this is a description of the different types of documentation required different types of documentation required (such as training manual, procedure (such as training manual, procedure manual, online help). It is a specification of manual, online help). It is a specification of the documentation to be produced.the documentation to be produced.


33

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


44


55

planningplanning draftingdrafting reviewingreviewing testingtesting producingproducing distributingdistributing updating.updating. PlanningPlanning


66

PlanningPlanning As in other disciplines such as constructing As in other disciplines such as constructing

a building or developing software, a building or developing software, planning is essential. Just as a builder planning is essential. Just as a builder would not start building a house without a would not start building a house without a schedule, specification and budget, you schedule, specification and budget, you should not start writing the documentation should not start writing the documentation without plan- fling first. As part of the without plan- fling first. As part of the planning process, you need to:planning process, you need to:

create a document library blueprintcreate a document library blueprint determine the resources requireddetermine the resources required develop a scheduledevelop a schedule determine the budget determine the budget


77

Creating a document library Creating a document library blueprintblueprint

Creating the document library blueprint Creating the document library blueprint involves identify all the pieces of involves identify all the pieces of documentation and how they are documentation and how they are related, and developing a specification related, and developing a specification for each — known as the document for each — known as the document specification. The document library specification. The document library blueprint and specifications provide blueprint and specifications provide the information the authors need to the information the authors need to produce the documentation.produce the documentation.


88

The individual document specification The individual document specification covers the documents:covers the documents:

I purposeI purpose I audienceI audience

characteristicscharacteristics needsneeds diversitydiversity related documentsrelated documents mediamedia production planproduction plan reviewing and testingreviewing and testing update plan.update plan.


99

PurposePurpose

The purpose of the document is to The purpose of the document is to define the technical problem being define the technical problem being addressed in the context of the addressed in the context of the business environment. This may be business environment. This may be addressed in the form of objectives addressed in the form of objectives for the documentation.for the documentation.


1010

Intended readerIntended reader

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


1111

Developing the scheduleDeveloping the schedule

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


1212


1313

Determining the budgetDetermining the budget

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


1414

DraftingDrafting

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


1515

ReviewingReviewingPurpose — are the objectives as stated in Purpose — are the objectives as stated in

the document specification being met?the document specification being met?

ContentContent 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 Style — is the writing style appropriate for the

intended user? intended user?


1616

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


1717

TestingTesting

The documentation is tested by people The documentation is tested by people who represent the users of the who represent the users of the documentation. For a software documentation. For a software application, testing involves using the application, testing involves using the documentation in conjunction with the documentation in conjunction with the software. software.


1818

ProductionProduction

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


1919

DistributionDistribution

Distributing the documentation means Distributing the documentation means making it available to the users of the making it available to the users of the computer system for which it was computer system for which it was designed. designed.

The documentation needs to be available The documentation needs to be available at the time of packaging.at the time of packaging.

Similarly with online documentation. If a Similarly with online documentation. If a CD is to accompany the product release, CD is to accompany the product release, whether hardware or software, it must be whether hardware or software, it must be pressed and ready. If online help is to be pressed and ready. If online help is to be present with a software application, it present with a software application, it must be incorporated into the software.must be incorporated into the software.


2020

UpdatingUpdating

Computer systems, both hardware and Computer systems, both hardware and software, are never static. Change is software, are never static. Change is inevitable as technology advances and user inevitable as technology advances and user requirements change. New models of requirements change. New models of hardware and new versions of software hardware and new versions of software applications are continually being developed applications are continually being developed and released. and released.

The documentation must reflect the changes The documentation must reflect the changes in the computer system.in the computer system.


2121

Version controlVersion controlIt is possible that there will be different versions of It is possible that there will be different versions of

documentation referring to different versions of a documentation referring to different versions of a software package these versions should be clearly software package these versions should be clearly distinguished. Both the name of the document and distinguished. Both the name of the document and the version should be indicated. Sometimes the the version should be indicated. Sometimes the name of the document will indicate the version — name of the document will indicate the version — for example, Microsoft Office 2000 distinguishes for example, Microsoft Office 2000 distinguishes that version of documentation from Microsoft Office that version of documentation from Microsoft Office XP.XP.

If the version is not distinguishable by the title, you If the version is not distinguishable by the title, you can indicate the version by using a version number can indicate the version by using a version number (or edition number), and the date on which the (or edition number), and the date on which the documentation is published.documentation is published.

Activity 1.3


2222

SummarySummary

The prime purpose of documentation is The prime purpose of documentation is communication. In information technology it communication. In information technology it provides information to people who are provides information to people who are developing, maintaining or using computer developing, maintaining or using computer systems.systems.

There are two broad categories of computer system There are two broad categories of computer system documentation: technical and user. Technical documentation: technical and user. Technical documentation is for the people who develop or documentation is for the people who develop or maintain computer systems; user documentation maintain computer systems; user documentation is for those who use the computer system for a is for those who use the computer system for a purpose. Documentation can be in printed or purpose. Documentation can be in printed or online form, or both.online form, or both.


2323

There is a standard documentation process for There is a standard documentation process for producing documentation. The methodology of producing documentation. The methodology of plan, draft, review, test, produce, distributes and plan, draft, review, test, produce, distributes and update is a simple but effective method of update is a simple but effective method of developing documentation.developing documentation.

Standards for producing documentation help ensure Standards for producing documentation help ensure quality and consistency.quality and consistency.

Standards can originate: at the industry level, such as Standards can originate: at the industry level, such as from the Standards Australia organisation; from the from the Standards Australia organisation; from the organisation, which may have its own standards; organisation, which may have its own standards; and from within the project of developing or and from within the project of developing or maintaining the computer system.maintaining the computer system.

Templates are specific tools used to help Templates are specific tools used to help documentation developers follow a standard layout.documentation developers follow a standard layout.


2424

Media for documentationMedia for documentation

The two main forms of media for user The two main forms of media for user and technical documentation are paper and technical documentation are paper and online. They perform in different and online. They perform in different ways, but have a common purpose.ways, but have a common purpose.

The choice of medium is determined by The choice of medium is determined by many factors. The most important is many factors. The most important is usability how well the documentation usability how well the documentation helps users of the application. helps users of the application.


2525

Paper-based Paper-based documentationdocumentation

Paper documentation is also referred to as Paper documentation is also referred to as print media, and includes manuals, print media, and includes manuals, reference guides and brochures (covering reference guides and brochures (covering a variety of appliances, tools and toys as a variety of appliances, tools and toys as well as computer hardware and software).well as computer hardware and software).

the features or functions of the equipment or the features or functions of the equipment or software applicationsoftware application

how to install or set it uphow to install or set it up how to operate ithow to operate it what to do, or who to call, if it doesn’t work.what to do, or who to call, if it doesn’t work.


2626

Online documentationOnline documentation

Online media use the computer Online media use the computer technology itself to deliver the technology itself to deliver the documentation. The most familiar documentation. The most familiar examples are messages to the user examples are messages to the user and online help. Figure 1.6 shows an and online help. Figure 1.6 shows an example of online help.example of online help.


2727

Internet/lntranetInternet/lntranet

The Internet has become a rich source of The Internet has become a rich source of information, including computing systems information, including computing systems documentation. Information about all documentation. Information about all types of hardware and soft ware can be types of hardware and soft ware can be found. Some information comes from the found. Some information comes from the suppliers, although much of it is from suppliers, although much of it is from other parties.other parties.

Documentation is often found on an Documentation is often found on an organisation’s intranet. It is not organisation’s intranet. It is not uncommon to find policies and procedures uncommon to find policies and procedures and computer system documentation on and computer system documentation on the intranet, rather than in printed form.the intranet, rather than in printed form.


2828

Help filesHelp files

Help files are common in many applications, Help files are common in many applications, reflecting the increasing popularity of online reflecting the increasing popularity of online documentation. Help files often provide documentation. Help files often provide detailed and structured information so that detailed and structured information so that the user can find what they want without the user can find what they want without the inconvenience of a bulky manual.the inconvenience of a bulky manual.

Help files can now be produced in HTML Help files can now be produced in HTML format using Microsoft’s HTML Help. These format using Microsoft’s HTML Help. These help files can be viewed by Internet help files can be viewed by Internet browsers such as Internet Explorer and browsers such as Internet Explorer and Netscape.Netscape.


2929

HypertextHypertext

Hypertext is a common online Hypertext is a common online technique in which information technique in which information appears about the word or picture appears about the word or picture being pointed to with the mouse. being pointed to with the mouse. These spots on the screen are These spots on the screen are sometimes called hotspots. sometimes called hotspots.


3030

WizardsWizards

Wizards are another form of online Wizards are another form of online documentation, in which instructions are documentation, in which instructions are presented on screen for the user to follow. presented on screen for the user to follow. The software automatically does common The software automatically does common tasks by using the information the user tasks by using the information the user provides in following the instructions. provides in following the instructions.

As an Excel Chart Wizard guides the user As an Excel Chart Wizard guides the user through the process of creating charts using through the process of creating charts using the information already inserted by the user.the information already inserted by the user.


3131

MultimediaMultimedia

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


3232

CD-ROMCD-ROM

CD-ROMs have recently overcome the CD-ROMs have recently overcome the storage limitations of online storage limitations of online documentation and now provide the documentation and now provide the cheapest and most flexible way of cheapest and most flexible way of providing documentation. Because of providing documentation. Because of this, CD-ROMs are particularly useful this, CD-ROMs are particularly useful for providing documentation that for providing documentation that contains a large amount of contains a large amount of information.information.

Activity 1.1

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

Documents

user documentation slide

planning planning slide

final documentation

document library blueprint

pieces of documentation

user technical documentation10

user technical documentation8

user technical documentation7