Store, organise and distribute IT documentation

The many uses of IT documentation

Types and attributes of documentation

Reference collections

Technical documents

Organising documentation

Why classify documentation?

The basics of a well organised system

Storing documentation

Physical storage

Different formats and location control

Electronic storage

Guidelines for online documents

Document control and distribution

Levels of security and confidentiality

Reporting, auditing and archiving documentation

Summary

Check your progress

The many uses of IT documentation

An IT organisation or department will accumulate many technical papers, records and books. Some documents and manuals may be easy to find, while others can be misplaced, lost or damaged. To avoid the latter, methods similar to the inventory of hardware and software can be applied to documentation.

In an IT support role, you may be called upon to provide a friendly information resource for clients. You should be able to easily find and use the information they need.

You may otherwise need to advise clients on:

  • what information is available and where it might be
  • how it can be found and retrieved (different media and formats)
  • how the information can be searched, stored or printed
  • how it can be sent to them.

Think about the types of IT documentation and when it may be needed or requested. You will need to answer requests quickly and effectively.

A customer may ask for:

  • a software manual, so to install a program
  • a manual to check compatibility with other hardware or software
  • instructions to perform a specific task.

A colleague may ask for work instructions such as how to:

  • reset a mainframe password
  • check a local are network (LAN) printer queue
  • set a computer for remote access.

A manager or auditor may ask for computer inventory records or software licensing records.

Reflection

The audience and the type of document request can be quite different. Can you think of other situations where IT documents are required?

Types and attributes of documentation

A document is information and the supporting medium that carries the information. The medium can be paper (hard copy), a magnetic, electronic, or optical computer disc, a photograph or master sample, or a combination thereof. A set of documents, such as specifications, records, manuals or plans is frequently called ‘documentation’.

Reference collections

If your organisation or department has a reference collection (and it should have) it could include books, CDs, DVDs, technical manuals and online resources that staff and clients use to find particular information.

Reference items that may be kept on open shelving (but must still be accounted for), include:

  • procedural and technical manuals
  • technical reference books and textbooks
  • catalogues
  • directories
  • manufacturer’s specifications
  • technical magazines, journals
  • case histories
  • training guides.

Software manuals on paper or CD ROM for a particular software program may be kept at the workstation running the application.

Document control

Working in an IT reference section you might be expected to handle changes to technical users’ manuals written by staff in your own IT department. Document control includes withdrawing old versions, disposing of them and issuing updated copies. To do this job efficiently, your records inventory must show who holds copies.

Technical documents

Technical information may need to be available throughout the organisation. Some documents will have limited access, some may be found on the open shelves in the IT work area, and others kept in client’s offices. In a highly developed business, images of documents can be online via the IT network.

Levels of access and the currency of documents

General access

IT documentation can hold details of flow charts, program code, technical reports, wiring plans, testing results, measurements and system analysis. These documents need to be sorted and identified with a key number and an emphasis on making the information accessible.

All documents have common requirements, they must be:

  • Available when needed: As in all human endeavours, time is a constraint in IT; documents must be available on request as most of the time the particular information sought will help decision-making.
  • Easy to find: In order to retrieve a document (to find a piece of information or update it) efficiently, it must be stored under a classification scheme.
  • Current (up-to-date): Normally, a document has an owner who is in charge of maintaining it, but in order to update a document, a business process called ‘change control’ must be followed.

Change control is the process of managing and controlling changes; requested or otherwise. It ensures that all work is justified and that all work requested and approved is completed and tested. In some organisations, no change can be made without an approved change control form.

Valuable originals and document security

Valuable original documents, possibly held in a protected place under the care of IT, may be:

  • legal or historical papers
  • signed forms
  • tender documents
  • contracts
  • agreements
  • warranties and licences.

These documents need to be sorted, identified with a key number, and filed (with a strong emphasis on security).They need to be accessible on a ‘need to know basis’ — this attribute is very important for information in IT documents that is confidential or sensitive and restricted to authorised access (specific individuals).

The objective of document security is to preserve the organisation’s information assets and the business processes they support, by:

  • Confidentiality: where documentation is accessible only to those authorised to have access
  • Integrity: where accuracy and completeness of information contained in the documents and processing methods are safeguarded
  • Availability: when documentation and associated assets are accessible by authorised users when required.
Document and file properties

One simple way to protect a soft copy document is to use the built-in security file features, now common to operating systems. Using this system, every object has a unique owner who has control of and access to it.

An object can be a folder, file (document) or a complete network drive. The access provided by the owner can be ‘read’, ‘write’ or ‘no access’. Owners can also revoke access to users. Typically, the department or a section within an organisation appoints the owner.

Normally, sensitive documentation is labeled ‘commercial-in-confidence’.

Organising documentation

Why classify documentation?

The purpose of classifying documentation is to store it in an organised manner. This then allows timely and easier access to the right documents when needed. More generally, documents can be managed in line with the organisation’s business goals and objectives.

The three main (and related) reasons why an organisation needs to organise its documentation, are that this:

  • allows them to find information more easily
  • allows faster response to any type of query
  • makes work easier.

The basics of a well organised system

Access, room to expand and ownership

Documents should be organised so that people are keen to use them. Users should not need to learn complicated hierarchies, or constantly refer to convoluted indexes to find a document — if a system is complex and hard to use, people end up not using it at all. The aim is to avoid people having to guess or make judgments on where to store or look for relevant documentation.

Issues of finding documents become increasingly more important as an organisation grows. A well-organised system should be flexible and able to grow to handle large numbers of documents and users.

Documentation should available to all persons or groups within the organisation on a ‘need to know’ basis. Attributing ownership to documents and folders makes it easy to establish responsibility for them, particularly when documentation needs to be updated.

The filing system and naming protocols

The filing system should help users retrieve documents quickly. A system of sorting the documents is at the heart of every filing method.

Some systems use alphabetic sorting, from A to Z. Yet with that method, there can be confusion as to the name of a document or a book, or if is unclear if the alphabet has been used for the author or title or subject, or even the date.

Similar confusion can occur in file management programs included in operating systems such as Microsoft Windows. The program makes it easy to create directories and folders, but one person may name a file by the first word in a document, another will give the file a code. All users need a common file naming policy.

File code numbers and bar codes

A widely adopted practice to overcome all that is to give every book, document and file a code or number. The items can then be sorted numerically on the shelves or in the file drawers. The number will be printed on the document, and is entered into the computer inventory along with its location.

Some large organisations add a barcode to items by a sticky label or printed onto each document. Entry into the computer database is then simply a matter of scanning in the way a supermarket scans items at a checkout.

Inventories

There should be an inventory of documents and reference materials. Depending on the amount of information, filing system and size of the library, the records for technical papers and manuals can be kept on a card index, or in a computer database.

Each document and reference should be numbered or coded, just as with the other assets of the organisation or company.

A record of those numbers, a description of the item and its location are then recorded in an index file or an electronic catalogue.

Naming convention for IT documents

IT documentation is an integral part of the foundation to comply with quality standards, such ISO 9001:2000, which outlines criteria for a good quality management system.

ISBN numbers versus numbering systems

Most books already have a number printed on the page with publication and publisher details, called the imprint page. This number is the International Standard Book Number (ISBN) or ISSN for International Standard Serial Number (for journals and magazines etc), used by libraries and publishers and which may be used in the inventory record. However, these numbers are long and cumbersome to find, read or write.

To make it easier, a separate filing number may be stuck on the spine of the book. Libraries use a numbering system called the Dewey Decimal system. A numbering system such as this can be used for both books and the file names for documents.

Storing documentation

Physical storage

A large range of office furniture and fittings can be used to store or display documents. Some are fireproof while others are designed to hold volume or quantity. You can see a variety of storage units used in different libraries.

Confidential documents may be kept in a very secure place, such as a storeroom.

Other books may be kept in bookcases or open steel shelves. Periodicals, journals, magazines and brochures may need to be kept in boxes on shelves, to help locate specific issues.

A large library will probably need a system of access to books called a Compactus, which is shelving on wheels, to allow more shelf space in a compact area.

Different formats and location control

Technical documents and help information are supplied on a variety of different media that the IT department must store and manage.

The different media include:

  • books
/
  • CDs
/
  • digital images
/
  • film

  • microfiche
/
  • Internet online
/
  • paper
/
  • video.

Each different media format may require different means of storage and sometimes, different ways of filing and management.

Your organisation’s bookshelves and files may be in a file room, a storeroom, a library or a person’s office. It is not necessary to keep everything in a central place. Many documents and manuals can be kept on shelves close to where they are most often used, even in peoples’ offices and by workstations. The important thing is to keep a record that shows where an item is at all times, and to ensure that any movements of the item are recorded in the database or inventory.

The inventory of documents ought to tell a searcher where a document, a folder, tape, disk or book is stored when no one is using it.

Electronic storage

Nowadays, it is more practical (and environmentally considerate) to store nearly all documents electronically.

If we value our documentation, it must not be stored on a local hard drive. It must be stored on a server that is regularly backed up.

Network storage

One proven system of storage, using a local area network (LAN), is based on the structure of an organisation.

On the organisation’s LAN, each major department or team is given its own folder: Operations, Customer Service, Administration, Human Resources, Payroll, Accounting, etc. Within the department folder, subfolders are assigned to different sections and projects.

Advantages of network storage
  • Each department and workgroup can own folders assigned to them. The department will manage its location, maintenance and access.
  • It is flexible and easily expandable to allow for growth: simply subdivide folders if more classification is needed.
  • It is flexible when business realignment occurs: departmental folders can be moved to reflect the new structure without disrupting their contents.
  • Departments are in charge of archiving documentation when they became out of date.

Formats for storing IT documentation

For a document to be available to customers, documentation must be stored in a file type that is widely compatible with a number of platforms. Documents cannot be stored in a format that the audience or user may not be able to open.

Let’s see some sample guidelines for online document publication in the next section.

Guidelines for online documents

Geographical distance is no longer a barrier to communication. Modern documentation is also increasingly distributed online, because it:

  • is easier to documentation keep up-to-date
  • is less expensive to produce
  • can be presented in a file format that can be used on any platform
  • takes up less space than printed materials.

The documentation kept on a server must not be allowed to become out of date (while the latest version is stored somewhere else) and unrestricted access should be avoided.

Online documents may be saved, stored and distributed in any of the following formats.

Hyper text mark-up language (HTML)

The main benefit of HTML is that the computer screen displays the file much faster, particularly over distance. Another major advantage is that HTML is designed for the web, intranet or Internet. The user can copy and paste content, including most formatting features, into any standard text editor, such as office applications.

HTML is the preferred publishing format for any typed documents. However, publishing in either native or PDF format should be considered if:

  • the physical size of the document does not justify the investment of time to convert to HTML (if, for example, it is over 40 pages).
  • the document contains many graphics (eg more than 10 images).

Native

Native refers to the original software used to create the document. For example, Microsoft Office programs such as MS Word, MS Excel and MS PowerPoint. The user can save the file to a local server or their PC or laptop, if the format is compatible.

Native format should be discouraged considering the potential number of different platforms used by customers (although this is increasingly less of a problem with cross-platform operating systems.)

Adobe Acrobat Portable Document Format (PDF)

Acrobat is a useful product for creating ‘snapshots’ of existing files that can be viewed by users who do not necessarily have access to the software that was used to originally produce the file. Adobe Acrobat Reader is available as freeware from the company who develop it. Files in PDF format are generally reduced in size from the original. A full Adobe Acrobat license is required in order to produce files in PDF format.

For compatibility issues, PDF is preferred over native format.

Document control and distribution

In an IT organisation or department, the controlled distribution of documentation is of paramount importance.

Levels of security and confidentiality

The inventory record of any document should show the security level.

High security — valuable originals, etc

Some documents in the care of IT must be kept safe, perhaps in their original condition. They may hold trade secrets or confidential information. Some documents are held in a form that is liable to damage and must be kept in a secure area, not to be removed, with even authorised people only able to access copies or images of them.

High security — critical information and fragile media

Original documents that may have a critical value, or be recorded on a fragile medium such as tape, should not be allowed to leave their secure storage place. Only copies should be taken out.

Medium security — sensitive and restricted material

Some records contain sensitive material, and may not be seen by all employees. Each document and each authorised user of a system should be assigned a security level. Unauthorised people can be denied access to the whole system. If a person’s security level were lower than the security level of a document or record, access would be denied.

Low security — general access required

Other documents might hold knowledge that is critical to the workings of IT equipment, but copies or images can be freely distributed, so long as the version of the document is clearly marked, and the reader has the necessary authority.

Hard copy documents

If a document is in hard copy, and the user is authorised to access it, the lender’s details can be recorded in a simple database to keep track of it

Sample loan database

Item / Restrictions / On loan by / Phone / Date / Return date

Soft copy documents

Distribution can be made secure and tracked by granting access to only the appropriate documents (by pre-determined levels of security) and by sending documents by email and filing/registering a copy of the email.

If the customer is off site, the email attachment must be in a compatible format. In the case of intranet html documents, usage can be tracked by the number of times that the page has been accessed, and privileges can be allocated of access needs to be restricted.

Reporting, auditing and archiving documentation

Your manager could ask you for a report on who has been using the technical documents listed in the index or inventory. You may need to show what’s been added, what’s been deleted, or transferred.