ICAD4217B Create technical documentation

There are many reasons for maintaining a complete and up-to-date library of systems and procedures for documentation. Without documentation that has meaning to the users, time may be wasted dealing with technical problems by duplicating answers to problems that have already been solved.

Other reasons for creating accurate, complete technical documentation include to:

• pass an audit, or quality certification
• create an accurate record of an organisation’s systems
• record maintenance
• identify the need to upgrade systems
• provide records for future decisions
• provide workers and stakeholders with a database for their jobs
• ensure work and service quality is consistent when staff changes occur
• add value to the organisation’s business and service.

Technical documentation provides a record of the functionality and processing of a system, program, network or application. The technical documentation should document how the system, program, network or application is structured, how it works and changes that have been made to it.

Task 1: Determine documentation standards

Activity 1: The uses of technical documentation

Q: Make a list of ten objects that you can see or feel from where you sit, that have technical documentation associated with them.

A: Answers for this question will vary, there are some example following:

1. When you switched on your computer, a technical document (a log in the computer’s memory) was created.
2. The software you are using was installed using technical documentation.
3. When you switch on your lights, a record is kept for billing purposes.
4. The chair you sit on was made from a plan.
5. The mobile phone on your desk has a help function.
6. When the chair was made, a quality check was recorded.
7. The air you breathe is monitored for pollution records.
8. The time on the clock is set to an agreed, international standard.
9. The clothes you wear were made to a pattern.
10. Your health is recorded in doctor’s files.

Activity 2: Identify documentation standards

Q: Identify at least two industry standards that relate to documentation. Use search terms such as: standards, documentation, technical, industry in your preferred search engine.

A: International Standards Organisation ISO 9000 Quality Standards (which is a family of different standards) that requires the processes involved in technical documentation to meet a certain level of quality, theses standards concern quality management systems. The Australian Standard AS ISO 10013-2003 relates to the documentation for the quality management system. ISO 14000 standards relate to environmental aspects of processes and can relate to such things as disposal and storage of documents and the media chosen for publishing documents. The ISO 9000 and ISO 14000 families of standards are those from which many organisation-based standards are derived.

There are many standards that can apply to software used by documentation and used in the delivery of documentation. Two groups of specific standards that relate to the design and production of technical documentation are the Australian Standards for Editing Practice produced by the Institute of Professional Editors (IPed), formerly the Council of Australian Societies of Editors (CASE), and the World Wide Web Consortium (W3C) onscreen accessibility guidelines. You may have found others that relate more specifically to your own study or work area.

Task 2: Determine technical documentation requirements

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, except for 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.

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

A: The 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

Q: 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?

A: The answer is depending on the product that i have bougth, if that product was the thing i have been used before. I am ever read or look at the instructions. However, if the product is come with the new technology or i never been use it for long time or that product is quite expensive. I might read through very quick to get some useful information.

Activity 3: The pros and cons of paper

Q: 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?

A: 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

Q: 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?

A: 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

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

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

Task 3: Design technical documentation

Activity 1: Types of documents

Q: Recall or identify different types of technical writing or documentation. Try to make a list of 15 different documents. Use an internet search engine to assist you in this activity, if you need to.

A: Table of technical writing or documentation examples—you may have listed other documents, which is fine.

Activity 2: Technical documents

Q: What technical documents have you seen or used? Note down as many as you can, the list may help you later. Alongside each document, note the good points, and any that you remember as not being helpful at all. Why were documents of a poor standard or with no standards less useful?

A: Documents at home might include:

• assembly instructions for do-it-yourself furniture
• the manual that came with your computer
• the blueprint for a house
• a text book for software development
• specifications sheet for your camera

Documents at work might include:

• system functional requirements with flow charts
• network diagrams
• computer programming language syntax manual
• functional requirements for a web site
• project work break down structure.
• Other comments you have made might vary even more greatly; yet you may have noted how documents of a high standard make it easier to understand, access and use technical information.

Activity 3: Information online

Consider the following scenario and do some research.

You are going to place documentation on the organisation’s intranet web site. You have two types of information to go on the site, with different audiences for each one. One type is technical documentation for software development and the other type is a manual about the use of that software. Even the words they use in different systems are different. You research the internet to find information that helps you decide how each different type of information might be treated on the site.

Q: Give a general outline of how the two different types of technical documentation in the scenario might be placed within the information architecture of a web site.

A: The software manual is technical information for technicians but also for users, it could be organised as a series of pages from a contents list or index and it might also have a glossary, index and search features for the general user. Glossary items might also be given their own pop-ups so that users can check terms as they go. Procedural parts of the manual might also be structured as a series steps that the user progresses through after they have checked the ‘next’ button (like those used in installation procedures).

The software development material is for an audience of technical readers or specialists, most likely IT staff. It might be accessible from a general navigation bar as the same level as the manual and provided as a choice of HTML pages or PDF files to select and download from a menu. For maintenance, a technician needs to find a procedure quickly, without all the solutions to other problems. They need to access information selectively. Individual specification sheets that can be downloaded and printed, or network diagrams, might be part of the documentation, for instance. Links to the software development documentation might also be placed at different relevant places in web pages for the software manual, effectively then at a lower level, and being there when users or specialists need additional, more technical information.

Activity 4: Documentation case study—functional specifications

Q: Research the Internet and find some information that helps you with the design of the technical documentation required for ‘functional specifications’ for software development. What sort of documentation would be required?

A: A functional specification for software developers is a formal document used to describe in detail a program’s intended capabilities, appearance, and interactions with users.

The functional specification is a kind of guideline and continuing reference point as the developers write the programming code. Typically, the functional specification for an application program with a series of interactive windows and dialogs with a user would show the visual appearance of the user interface and describe each of the possible user input actions and the program response actions.

A functional specification may also contain formal descriptions of user tasks, dependencies on other products, and usability criteria. Many companies have a guide for developers that describes what topics any product’s functional specification should contain.

Task 4: Obtain client sign-off on technical documentation

Activity 1: Sign-off and quality management

Where do sign-off procedures fit in with your organisation’s quality management policies?
By this stage of your learning you will have discovered that some organisations use the ISO 9000 family of standards as a basis to certify the quality standards of their processes, other organisations prefer alternative measures, such as Six Sigma.

Q: Using a web search engine, research the fundamentals of ISO 9000, and find where sign-off procedures for documents fits into the system? Write a brief report on your findings (about 250 words).

A: If your organisation has quality certification, ISO 9000 sets out the requirements for your quality management system. ISO 9000 is not a standard for ensuring a product or service is of quality; rather, it verifies the quality of the process, and how it will be managed and reviewed. So ISO 900 doesn’t guarantee the quality of the technical documents, it lays out the rules for the process for sign-off

Hence, ISO 9000 is directly related to your organisation’s procedures for sign-off, and those procedures may vary from one organisation to another.

There are four types, or levels, of documentation you will need to manage to achieve ISO 9000 standards for sign-off. These four levels form a hierarchy. The more detailed the document, the further down it belongs in the documentation hierarchy

Table: The ISO 9000 documentation hierarchy

Fourth-level documentation includes all the records and forms which are generated by the working system.

ISO 9000 document generation and control

Under ISO 9000, every department issuing documents is free to designate its own procedures and channels for processing documents, including sign-off. This is a matter for your organisation to manage. Your management defines what your distribution network is, and who has authority for sign-off and release of procedures.

• Authority—Define who has the authority to sign off on documentation changes?
• Obsolete Documents—Describe what you do to these (shred, archive, etc).
• Distributions—Who gets the documents?
• Identification and revision—How do you identify documents? How do you track their revisions?
• Appendices and forms—Do you include appendices containing extra reference materials pertaining to each document for sign-off?

Key terms

Configuration management: Configuration management refers to the storage and security of documents.

Glossary: A glossary is a list of words used in a document and can include key terms, specialist terms or terms likely to be new to readers or users of the document; glossaries can also include a list that spells out acronyms used.

International Electrotechnical Commission (IEC): The International Electrotechnical Commission (IEC) is concerned with standards and conformity assessment for government, business and society for all electrical, electronic and related technologies.

International Organisation for Standardisation (ISO): The ISO is a standard-setting body composed of representatives from national standards bodies.

Jargon: Language that is peculiar to a trade profession or other group, unexplained jargon or overuse of jargon is a common fault of poor technical writing.

Metadata: Metadata is data about data or planning information about a document. Metadata provides information about the content, quality, condition, and other characteristics of a document.

Requirements: Requirements in this instance are what an organisation needs to support its goals and operations in regard to technical documentation, and can range from the content and functionality of the documents themselves, to the system of document control and distribution.

Scope: Scope relates both to the level of functional detail and depth for individual documents (no matter what media), and to the extent of work required in the process of creating technical documentation.

Standard: A standard is a basis for comparison, a reference point against which other things can be evaluated.

Standards Australia: Standards Australia is an independent, non-government organization, which, through a memorandum of understanding, are recognised by the Commonwealth Government as the peak non-government standards body in Australia.

Substantive editing: Substantive (or structural) editing involves an overall assessment of wether a document’s content, structure, language and presentation need improvement to meet the publisher’s and reader’s purpose and expectations, and any work from this. It is the stage before copy editing and can be done alongside a technical review of the document by a subject expert.

Technical manual: A technical manual can include properties, methods, events and controls for products or systems. It can include specifications, definitions and acronyms. (Few technical manuals answer all the questions, for all users and need to be cross-referenced from one document to another).

Technical resources: Technical resources can range from single-sheet specifications, manuals, CDs, online data or a small library offering a wide scope of information and covering subject matter in detail.

Template: A template is a document, much like a stencil or a model, which can be used over and over again without changing the original. Templates are a special type of document that can hold text, styles, macros, keyboard shortcuts, custom toolbars and AutoText entries.

Typesetting: Once this term described the physical process of setting metal type and now describes the work in formatting documents in page layout programs such as Quark or In-Design.

Use case: A use case is a description of how end-users will use a technical document, such as a software code. A use case is a way of specifying the end-users’ expected use of the software.

Version control: Version control is part of the management of documents to ensure the latest version is used, to ensure the accuracy of documentation that has been subject to review or editing, and that the version being used is the most up-to-date.