Technical Documentation and Process

Jerry C. Whitaker, Robert K. Mancini

• Publisher: CRC Press
• Year: 2018
• Print ISBN: 9781138422117
• eBook ISBN: 9781351833035
• Edition: 1
• Topic: Technology & Engineering
• Subtopic: Electrical Engineering & Telecommunications
• Index: Technology & Engineering

We live in an age of electronic interconnectivity, with co-workers across the hall and across the ocean, and managing meetings can be a challenge across multiple time zones and cultures. This makes documenting your projects more important than ever. In Technical Documentation and Process, Jerry Whitaker and Bob Mancini provide the background and structure to help you document your projects more effectively.

With more than 60 years of combined experience in successfully documenting complex engineering projects, the authors guide you in developing appropriate process and documentation tools that address the particular needs of your organization.

Features

• Strategies for documenting a project, product, or facility
• A sample style guide template—the foundation on which you can build documents of various types
• A selection of document templates
• Ideas for managing complex processes and improving competitiveness using systems engineering and concurrent engineering practices
• Basic writing standards and helpful references
• Major considerations for disaster planning
• Discussion of standardization to show how it can help reduce costs
• Helpful tips to manage remote meetings and other communications
• First-hand examples from the authors' own experience

Throughout, the authors offer practical guidelines, suggestions, and lessons that can be applied across a wide variety of project types and organizational structures. Comprehensive yet to the point, this book helps you define the process, document the plan, and manage your projects more confidently.

1

Overview

1.1 Introduction

The subject area encompassed by “documentation and process” is broad in scope. It includes, but is not limited to, writing, organization, people management, project management, and problem-solving. Within each of these broad groups, additional distinctions can be identified; indeed, entire books have been written on these subjects. Beyond a deep dive into these and other topic areas, there is a need to see the big picture and integrate separate disciplines into a cohesive program or process.

The lessons of documentation and process can be applied across a wide variety of project types and organizational structures. This being the case, guidelines, suggestions, rules, and all the other elements that make up a process rarely are applied strictly to an organizational structure. Instead, that structure is executed and maintained by individuals. It is important, therefore, for those individuals to understand the process and take ownership of it.

While an ad hoc approach to a given project can be successful, the likelihood of success may be reduced due to the informal nature of the activity. Equally important, lessons learned during execution of one project may be lost and forgotten when the project is completed. One benefit of defining a process is that it compels the leadership to look at the big picture and to try to anticipate unforeseen challenges.

Process development is an inexact science. However, by documenting the lessons learned on past projects, the knowledge base of the organization grows. This learn-by-doing approach implies that a process developed for a given project may change over time as unexpected problems are encountered and solved.

Documentation skills come into play here as well. Documentation also, of course, touches many areas of business and plays a major role in the success of a project or product.

1.2 Plan for Success

Well-thought-out and documented plans increase the likelihood of a successful project. A structural process that cannot be implemented in a given organization is certain to fail, and the individuals tasked with carrying it out may fail as well. Success has many fathers; failure is an orphan. This well-known truism has been proved right countless of times in any number of organizations over a long period of time.

While the reasons for failure vary from one situation the next, certain common threads tend to emerge, including the following:

•The goals were set too high. In business, as in most everything else, you can’t always get what you want. The needs of the organization must be balanced with the realities of resources, time, and capabilities. It is always a good practice to challenge individuals and organizations to produce their best; however, setting goals so high they are generally believed to be unachievable often results in team members giving up when the impossibility of the task ahead becomes clear.

•The goals were set too low. If a project is completed but the end result does not meet the need, then the effort can result in failure, or at least lost time as the project is rescoped and restarted. Individuals like knowing they are a part of something big, something important to the organization. A small project with only a minimal chance of having a positive impact invites lackluster participation and effort on the part of contributors.

Between these two extremes, naturally, there is a sweet spot where the organization and individuals within it are challenged with achievable goals and given the resources necessary to accomplish the task at hand. Although there are numerous factors involved, elements of successful projects may be generally summarized as follows and illustrated in Figure 1.1:

•Adequate resources. A project starved of resources is in trouble from the start. Typically, such resources translate into available personnel and money. The two are usually interrelated, of course. Other types of resource limitations include insufficient time made available on specialized machines or in research labs for focused work, restrictions on travel, and so on. The resources allocated to a project say something about the importance of the project to those tasked with carrying it out. If management doesn’t think a project is important, then the employees are unlikely to put much effort into it.

•Adequate time allocated. The time needed to complete a project is closely related to the resources applied to complete the project. Adding resources usually shortens time, while reducing resources usually lengthens time. In some situations, the timeline is fixed in that a project (or product) needs to be completed by a specified date (e.g., promised ship date to the user). In other situations, the timeline is flexible, with no firm end date (although there is often a goal). As a practical matter, projects with no end date tend not to end. An end date is important—but as before with goals, the date needs to be realistic. Personnel working on the project need to understand what the deadlines are and why they are important to the success of the effort.

•The right people in the room. This challenge can be a tough one to solve. It is related to resources, but has a unique dimension as well. In any organization, there are key individuals who either direct development or make decisions about development. As such, it is important for them to be involved in the projects and processes that will fulfill the goals of the organization. Getting a slice of their time may be a challenge. If a key person is not involved, the project will tend to move on but with the risk that when the decision-maker becomes involved, it may be so late in the process that it derails or seriously delays the effort. One approach that often works well is to identify key points in the process where review takes place. This permits the key players to focus on other tasks most of the time, but step into a project at predetermined points to provide input or to suggest changes.

•Well-thought-out design. An organizational structure can have considerable inertia. Once a project has begun, it usually rolls forward. Occasionally, after some work in a particular direction, it may become clear to decision-makers that the original concept or technology was flawed, and the best approach is to go in an entirely new direction. This can be wrenching to individuals who have put months or even years into a project only to have it stuck on the shelf. The decision to kill a project or take a radically new approach is difficult to make for a number of reasons, not the least of which is the knowledge of wasted resources. Still, cutting losses may be the best approach, as the only thing worse than stopping a project midstream is to complete it, only to find that it is not what the customer wants or otherwise fails in the market.

•Realistic view of expertise. Some concepts are exciting and hold considerable promise in the marketplace. The problem is that they can also be very difficult to implement and may require expertise that just doesn’t exist within the organization. As noted with goals, stretching the capabilities of an organization is generally good, but being unrealistic about what can be accomplished is not. There are a number of possible solutions to such a challenge. One would be to partner with another company or organization that has the needed expertise, with each party bring something different to the table. Business issues naturally come into play here; still, it may be an area worth exploring.

•Building the team. Teamwork is essential to a successful project—and one element of a successful project is the energy and enthusiasm behind it. A lack of energy and interest in a project is often the result of a combination of the challenges previously outlined. Most organizations can identify one or more projects that have plodded along to completion, but that generated very little energy, interest, or enthusiasm on the part of contributors. The end results are, predictably, uninspired as well. One important task of management in any organization is to motivate individuals. When they lack motivation, people do not produce their best work.

FIGURE 1.1
Elements of a successful project.

Just as individuals can be set up to succeed, or not, projects and processes can also be set up to succeed or fail. The role of management is to foster the former while preventing the latter.

Timing is another component in the success of a project. Some elements of timing are within the control of the organization and are set in the project timeline, as discussed previously. Other elements of timing are outside the control of the organization. For most things, there is a window of opportunity. The window may be large or small, and it can be very difficult to predict opportunities that are one, two, or three years out. There are numerous examples of a product that was offered to the market ahead of its time, when the market was not ready for it. There are probably many more examples where a product hit the market too late, having been overtaken by other technologies or approaches.

Market prediction can be a very difficult task. It involves—but is by no means limited to—market research, trend analysis, customer interaction, technology assessment, and luck.

1.3 Elements of Process

Process, within the scope of this book, focuses on the steps and structures needed to accomplish a set of stated goals. These steps include developing an organizational structure, coordinating the activities of participants, monitoring progress, documenting results, planning for unforeseen problems, and reporting the results of the work. The process developed for one group within a particular organization is often transferable to another group working on a related (or even unrelated) project. Such repurposing of management structures is helpful in that it reduces the time needed to begin work and tends to refine the individual process steps. Improvements in the process can be identified through documentation of things that worked well, and documentation of things that did not work as intended.

Process involves looking at the big picture and identifying the key steps necessary to get from here to there. The best structure is often a loose one, where guidelines and guideposts are established at key points along the way, but not so much detail and structure that it inhibits progress and creativity in the face of unforeseen events.

Invariably, documentation comes into play at all steps in a given process. Communication of ideas, problems, and solutions is essential to keep all members of the team on the same page, and top management advised of the status of important projects. One of the tools for the documentation specialist is a style guide that helps give structure to the overall effort and helps to maintain consistency and quality among documents from different groups.

Likewise, meetings are a critical element in any process. Meetings can serve as an opportunity to develop new ideas and concepts. They also give contributors a common vision of the task at hand. And, critically, they serve as a vehicle to make key decisions.

It is easy to find examples of process gone wrong. Meetings can turn into shouting matches. Documents can be inaccurate and difficult to read. The output of a long effort can fail to achieve the stated goals or requirements of the user. Such experiences reinforce the need to develop and refine process steps to maximize the probability of success. No process is perfect or can guarantee a winning product. In the end, success requires the right people working toward a common goal with the backing of management to provide the necessary resources to get the job done.

1.3.1 Documentation

It is difficult to thrive in the business world today without effective communications skills. Foremost among these is the ability to clearly communicate ideas in written form. As e-mail st...

Table of contents

• Cover
• Half Title
• Title Page
• Copyright Page
• Table of Contents
• Preface
• Acknowledgment
• About the Authors
• 1. Overview
• 2. Equipment Documentation Strategies
• 3. Developing a Style Guide
• 4. Meetings
• 5. Systems Engineering
• 6. Concurrent Engineering
• 7. Disaster Planning and Recovery
• 8. Standards and Reference Data
• 9. Document Templates
• Index