Document Management

Introduction

Document Management is a boring but important part of engineering, design and production. Documentation has got to be done. Doing it should not consume excessive resources. Typically, you need to do an adequate job, consuming a minimum of resources in the process.

This article is based largely on my forty years of experience working with and managing documentation. The generation of documentation is a job for appropriately specialized engineering types, and outside our present scope.

We have documents. We need to...

• ...store our documents in some sort of secure "vault".
• ...track changes anybody makes to the documents.
• ...identify and track any problems with the documents.

We will discuss generalities here. There is software for managing documents, and all sorts of literature and discussion on how to use it. We are interested here in the program objectives, not the tools.

Rule #1

1. Work gets done.

Under no circumstances should procedures and tools intended to increase efficiency hold up work.

Management

What do we want?

1. We want complete, accurate documentation.
2. Failing that, if the documentation is complete but it contains mistakes, we can fairly easily correct the mistakes. We exploited the opportunity to capture information from the design team.
3. If the documentation is not complete, we at least captured some information. No doubt, some of it is wrong.

The big failure with documentation is that it does not get done. We have no information. The designers have moved on to other projects, and possibly, other organizations. The product has shipped. Time has passed. Creating any sort of useful documentation will be a challenge. Often, documentation is not done because a manager fears mistakes. People who do not make mistakes do not make anything.

Your first problem is ensuring that your designers write stuff down. We all are focused on shipping hardware. The documentation seems less important and interesting. On a one-off in-house project, this may be true. For any sort of manufacturing, documentation is absolutely critical. Designers must be willing and able to communicate.

Most document management tasks are left to clerical level people, who have limited authority. This is not a field that attracts creative people anyway. Many people are process driven, and lack abstract thinking skills. This can create problems. Large software applications like databases and CAD are tools. People with limited abstract reasoning, will operate the tool, rather than do the work. Procedures are followed. Objectives are ignored.

Listen carefully to discussions. People will talk about an icon in a PDM (Product Data Management) window. They will not understand that the icon is an abstraction of a document, which is in turn an abstraction of an assembly that has a mass of 60kg, that requires four people to lift it, and that had darn well better be on your customer's loading dock by the tenth of next month.

The term used throughout this document is "document management". There are fancy initialisms for this, but actually, this is what we are doing. The term serves as a name, a mission statement, and scope.

Acronyms and initialisms inhibit meaning. For example, ECR stands for Engineering Change Request. An ECO is an Engineering Change Order. An ECN is an Engineering Change Notice. None of this means anything to people who are not curious. Is the word "Engineering" really necessary? "ECR" and "change request" each are three syllables.

• "You must fill in an ECR."
• "You must fill in a Change Request."

Some acronyms and initialisms are useful...

KISS

Keep It Simple (Stupid).

N³

Nice, but Not Necessary.

Simple, convenient procedures get followed. If you do not need something done, do not insist on it being done. The standard excuse for not following procedures is that documentation is not the real work, and there is no time for it. If your process is simple, your engineers and designers will do it. Complex processes requiring a lot of work, will be offloaded onto clerical staff who will not understand the information they are processing. Is the extra capability of your process actually providing value? [Note 1.]

Watch out for control freaks. There are all sorts of software tools that can prevent unauthorized work, from Windows ACLs [Note 2.] to PDM and PLM (Product Lifespan Management). Control freaks will use these tools aggressively, and prevent work. If someone is focused on operating the software, some very weird, stupid stuff could make sense.

Unauthorized document changes are not a serious problem. On any computer network, you have no business not doing backups. PDM/PLM software now is ubiquitous, and necessary for 3D parametric CAD. If a file should not have been changed, recover it from the backup [Note 3.], un-archive the old version from PDM/PLM, or just cancel the change. Your people should not be working on the one and only copy on their Windows C: drive.

Control freaks can be aggressive about document format. Consistency is nice (N³), but you don't want to reject valuable, critical, accurate information just because it is not on the right form. This may be your last chance to capture it.

PDM/PLM software should not control work processes. Professionals do not just generate documentation. There is an analytical process that requires a lot of training and experience that your PDM/PLM people almost certainly do not have. Their ideas on how to perform specialized technical tasks probably are wrong. Any flow charts or programmed work flows they set up, will prevent work.

The time comes when we all work in a blind screaming panic. Try very hard to minimize this. In panic mode, all seemingly unnecessary stuff gets ignored. If there is no time to write stuff down, stuff will not be written down. The information will not be available when the product must be serviced, or designed further. If you persistently do not have time to do documenation, you have a bad process, or you do not have enough people on the job.

Security

The following security model will be followed through the rest of this document.

Secret

information is released inside and outside the organization at the discretion of management.

Proprietary

information is accessible to all within the organization. It is released outside the organization at the discretion of management.

Public

information is accessible to all within the organization. It is released outside the organization at the discretion of employees.

Secret information could be new technology, customer information released to the organization with an NDA (Non-Disclosure Agreement), personal information like credit card data, or it could be a national secret. Management should deal with this case by case. Presumably, it will be released to appropriate people, on a need to know basis.

The document containing the information, and the vault containing the document must be at the security level of the most critical information. In other words, if the information is secret, the document and the vault are secret.

Public security is needed because employees have to send information out to vendors and customers. An elaborate management process to vet outgoing documents will be expensive and counter-productive.

People preparing documents must understand the security level. Proprietary documents must not contain secret information. Public documents must not contain secret or proprietary information. If PDM/PLM databases are set to anything more than proprietary security, you will have problems getting work done. Secret documents should be handled and stored separately.

Vault

We need to store documents in a secure place, where they will not be lost, deleted or irreparably modified. We would like to track any changes to the documents.

Before computers became a core piece of office technology, documents were written or typed, and stored in a file cabinet. The file cabinet could have a lock on it. The file cabinet could be located in a room with a locked door. With computers, the term "vault" is a metaphor rather than a real thing. Documents can be stored as files on a hard drive, and protected by ACLs or file permissions. The hard drive is backed up. Files improperly modified or deleted, may be recovered.

Secret information should be stored on secure computers and hard drives. The computers and drives should be located in locked rooms. Your network connections should be monitored closely. Maybe you don't need network access to this stuff! You must have system administrators cleared to access the secret information. You need a backup system that is contained within the secure environment.

Most engineering departments use PDM/PLM software. With 3D CAD and externally linked files, this is pretty well necessary. Documents are created and checked into the vault. When the document is to be modified, it is checked out of the vault, modified and checked back in again. The software logs the event. The earlier versions of the document are archived. At the very least, it can be seen who generated the document, and who modified it, and when. You can recover the archived version. For data integrity and security, this is ninety percent of what you need.

PDM/PLM can restrict write and even read access to files. Make sure work gets done.

Change Management

We need to...

• ...identify things we want changed -- change requests.
• ...change documents.
• ...log the document changes, who changed it? What changed? Archive the old documents.
• ...track the change request. Have we fixed the problem yet? Why did we change that document?
• ...validate working documents. Are changes pending on the document we are about to use?

You need a process for reporting problems. A change request is primarily a tool for capturing information. Control freaks will restrict authority to create these things. Resist this. The change request should be written by whoever is having the documentation problem. This may be an engineering manager. It may be a worker on the production line. It may be a salesperson. It could be the cleaning lady. The document to be changed may be fully released to production. It may be preliminary. It may be a figment of some designer's imagination. If there is a problem, we need to know it.

The person writing the change request may propose a solution. There is no particular reason why this person should be able to solve the problem. Ultimately, engineering is responsible.

Engineering reviews the change request. Perhaps it is not really a problem, in which case, it is closed and archived. The cleaning lady's ass is covered.

If it is a problem, engineering investigates, does the analysis, and works out the solution. This may result in updates to documentation. It may not. Maybe we need to buy production tools, or train workers, or explain things to customers. The change request is updated to show meeting notes, decisions made, and updates to documentation. The change request is closed when, and only when, the original problem has been solved.

Change requests contain discussions of proprietary documents, and possibly editorial content best kept behind organization doors. These must be at proprietary security.

Some organizations do change orders (ECOs). Change orders need not correspond exactly to the original change request. One change request could generate change orders to several people. A change order could come from several change requests. Remember N³ and KISS. You can implement change orders later if you really need them.

Get it done

Accuracy of documentation is generally outside the scope of this article. Consider the following. A document is generated early in the program. It is accessed, discussed, and updated by various people as time goes by. On a similar program, the equivalent document is generated at the last minute in a blind screaming panic. Which of these two documents will be more accurate?

There are many areas of engineering that require a safety culture, where everyone is cautious, and mistakes are not tolerated. Document management is not one of these.

• Keep it simple.
• Build to-do lists.
• Encourage initiative.
• Failure = work not done. Unauthorized work is not a big problem. If you have file backups and PDM/PLM, you can fix mistakes easily.

Notes

1. As a mechanical designer, I have been in discussions about who should do fabrication drawings. I firmly believe that the designer should. I know what tolerances and material specifications are needed. As the designer, I must take a final, detailed look at the part. Preparing the fabrication drawing accomplishes this, and it gets the drawing prepared. If the task is handed off to a CAD operator, the requirements will not be understood, and communicated to the fabricators. Drafting problems that affect design, will not be recognized. [Back to document]
2. ACL stands for Access Control Lists, used to control access to files on Microsoft Windows servers. The UNIX equivalent term is "file permissions". [Back to document]
3. When people make mistakes and need things recovered from the backup, your system administrators need to be nice. If the encounter with sys-admin is unpleasant and humiliating, people will find ways to avoid the problem, that may break your process and possibly your data security. This is your opportunity to test your backups! [Back to document]