Practice

Contents

Activity 1: Documentation for programs
Activity 2: Documentation requirements
Activity 3: The pros and cons of paper
Activity 4: The pros and cons of digital media
Activity 5: The pros and cons of video
Activity 6: Choosing media types

Activity 1: Documentation for programs

Note the following scenario:

Your organisation’s software development team has been complying with all the documentation requirements for the development of new programs,exceptfor one issue.

The comments in their code, telling others what they’re trying to do with their program are random, cryptic, and inconsistent.

You are asked to write specifications for comments in programs. The conventions should apply to any of the languages used by the programmers for the organisation. The constraints and rules imposed on programs should be as simple as possible.

Top of Form

What are some specifications that could be used for commenting within a program? Interview someone working in software programming or search the web for some sample specifications.

Your specifications for comments within the code could include that:

  • an overall comment should be included at the start of the program to identify the framework of the program or changes to the program
  • comments should be used to describe the code that is not apparent
  • all comments should be preceded by a blank line
  • arguments should be commented if they are not clear
  • comments should be aligned with the code.

Activity 2: Documentation requirements

Top of Form

Think about the last time you purchased something that required installation or that you had to put together yourself. Did it come with instructions? Were the instructions complete, comprehensive, useful, coherent, accurate, accessible and clear? Did they help you or did you not refer to them at all?

Answers for this activity will vary. Did you think of lots of examples of good documentation? Or, are your experiences with documentation not so positive? When you are determining your technical documentation requirements, be sure to think about the end use of the documentation.

Activity 3: The pros and cons of paper

Top of Form

There are probably times when you would use one medium in preference to another. What do you think are the advantages and disadvantages of paper-based documentation as a means of learning about a program or a system?

Some of the advantages of paper-based documentation include:

  • most people feel comfortable with books—they can write notes in them and they can read them without a computer
  • they have the benefit of using the actual software while following the manual
  • paper as a physical medium is easily handled by the user
  • novice users, or those who are not computer literate may not be able to use on-line help
  • paper-based documentation allows the user to add in their notes and bookmarks
  • manuals can be modular to target the needs of various user groups
  • paper-based documentation is portable, and production costs are less when compared to some other forms of digital media (DVDs etc)
  • paper can sometimes offer greater detail than other media.

Some of the disadvantages of paper-based documentation include:

  • paper deteriorates physically over time with use
  • a manual is more difficult to update and provide flexible access methods
  • it can not include sound or animation
  • the physical size of a manual can be intimidating, which can put people off
  • paper documentation must be massive to be able to cater for all the user needs, but individual users will usually only use parts of it
  • it may cause the user to shift concentration from what they are doing to the manual.

Activity 4: The pros and cons of digital media

Top of Form

What do you think are the advantages and disadvantages of digital or computer-based documentation (other than video) as a means of learning about a program or a system?

The advantages of computer-based documentation include that:

  • it can be flexible, provide vast amounts of information, and can integrate sound, text and animation
  • it can be context-sensitive, providing help directly relevant to the function being used or to the task
  • it is of great value in training and in advanced help features, like wizards and cue cards
  • it is easy to update and revise, efficient to store, and cheap to distribute
  • it can allow interaction
  • no paper is needed
  • it has cheaper packaging (CDs)
  • immediate reference is possible (you don’t have to search for the manual).

The disadvantages of computer-based documentation include that:

  • it requires computer literacy
  • it often requires various plug ins to access files
  • the computer screen places limitations on use
  • it may require swapping from the task to the documentation, causing distraction from the task at hand
  • as video it can take up large amounts of memory and be cumbersome to download.

Activity 5: The pros and cons of video

Top of Form

Describe some and advantages and disadvantages of using video-based documentation to learn about a program or system?

The advantages of video-based documentation include that:

  • it can provide a rehearsed and thorough demonstration or walk-through of a software application
  • it best suited for presenting animation, sound, graphics and ‘real-life’ presentations
  • it is good for training and promotion
  • learner retention is generally higher than for printed media (it is generally more engaging)
  • suitable for groups as well as individuals
  • DVDs are inexpensive and easy to distribute (although development costs may be high)
  • no paper is needed.

The disadvantages of video-based documentation include that:

  • video requires specialist equipment and personnel to produce; the cost may be high for complex, multimedia material
  • sequential access—while video is good for demonstrating sequential tasks, it is unsuitable for random access tasks as found for example in reference guides
  • it is non-interactive and does not cater for different levels of users
  • it can be easy to pirate
  • it is expensive to update—a new video must be produced (rather than a new version of a paper of digital print resource)
  • documentation is less detailed if reliant on video only.

Activity 6: Choosing media types

What medium/media would you recommend for thisscenario(.doc 38KB)? Use the table provided to help you to select the most suitable. Assess the appropriateness of each type against the project criteria in the scenario.

There is no right or wrong answer to this activity. Its purpose is to get you to think about the suitability of each medium for a particular project and make a decision based on the information provided. Your aim is to make the most suitable choice for the purpose. Here are some of the possible reasons for making your choice:

Suitability table
Medium / Suitability
all paper-based / Not really suitable for clients who are experienced online users.
all computer-based / Meets most criteria but may not suit promotional requirements
all video-based / Not suitable for interactive learning and quick reference but ideal for promotional and initial training purposes.
combination of media / A multimedia solution is probably the most suitable particularly as the budget allows for it. The combinations could be any of the following:
  • paper- and computer-based
  • computer- and video-based
  • paper/computer/video based.

Resources

On the web

General help

The New York State, Office of Technology is charged with coordinating New York State’s vast technology resources. Use the search facility on this site to find the Cookbook for Electronic Document Management Systems, at

Construx Software was founded in 1996 to provide practical, real-world support to the software community. The site is a useful place to check out templates and checklists that might be useful. While access to the templates will require you to become a member, membership however is free, at

Style guides and documentation—examples

The Institute of Electrical and Electronics Engineers Standards Association (IEEE-SA) is the leading developer of global industry standards in a broad-range of industries, including IT. See if you can find the latest IEEE-SA style guide for automated text mark up language (ATML), as an example of a style guide, by using the search facility on the site, at

Jungo Software Technologies is a provider of software and hardware technologies that has an extensive database of technical documentation. Use the search facility on the site to find the page that lists all these documents, at

On the Sydney Olympic Park web site, under the Corporate banner click on Document Library for an extensive list of reports and documents produced by the Sydney Olympic Park Authority, at

Self check

Try this quick quiz before moving on

Are you familiar with the learning contained in this resource?

If you have trouble answering some of the questions below, you may want to review the content in this Learning Pack before you continue. Talk to your study colleagues about areas you’re having particular difficulty with—they may have the same questions as you!

Question 1

Top of Form

How is technical documentation different from user documentation?

Technical documentation is very specific in its purpose; in the IT industry it is for use by specialists who develop and maintain the software and hardware, for instance. It contains technical information about the system, including software and hardware components. Examples of this type of documentation include forms, reports, product specifications and operating procedure manuals.

User documentation is for the users or operators of the application who carry out the business functions of the organisation, such as data entry operators, finance officers, executives and managers. Examples of this type of documentation are simple manuals aimed at users, training manuals, online help and tutorials, and policy documents and licensing agreements.

Bottom of Form

Question 2

Top of Form

What is the audience that technical documentation is written for?

Managers, technical staff and operators all use technical documentation.

Bottom of Form

Question 3

Top of Form

What are some questions that you may ask to gather requirements about your technical documentation?

Some questions that you may ask to gather information about your organisation’s technical documentation requirements many include:

  • What documents does the organisation need?
  • What documents exist that aren’t necessary?
  • What are the documents used for?
  • Who uses them?
  • What information should they include?
  • What format will they have?
  • What style will be used?

These are just some of the questions that you may ask. Did you think of any others?

Bottom of Form

Question 4

Top of Form

Are any of the following categories of requirements that should be considered for technical documents?

business requirements

technical requirements

functional requirements

information requirements

all of the above

All the categories (business, technical, functional and information) requirements should be considered for technical documentation.

Bottom of Form

Question 5

Top of Form

What are some techniques that you can use to find out your requirements?

Techniques that you can use to find out your requirements are:

  • interviews
  • checklists and templates
  • workshops and use cases

Bottom of Form

Question 6

Top of Form

Which of the following would not be an attribute of a good document?

Contains factual and correct information

Includes headings, subheadings, indexes and table of contents

Careless use of fonts and page design

Contains only relevant information

Easily understood by the intended audience

You should avoid careless use of fonts and page design.

Bottom of Form

Question 7

Top of Form

Is the following statement true or false?

Revision control of your technical documentation is not important for all technical documentation.

The design of any technical document should allow for control of the quality of the work and for future changes. Research shows the most frequently cited reason for failure to earn quality standard certification for technical work is inadequate document control.

Bottom of Form

Question 8

Top of Form

How might you consistently ensure your documentation has the necessary information included for good version control?

If you create a template with a place for version information on documents you may be better able to consistently ensure your documentation has the necessary information included.