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 standardsQ: Make a list of ten objects that you can see or feel from where you sit, that have technical documentation associated with them.
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.
10Your 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.
