Measure Twice and Cut Once: The Importance of Creating Detailed Requirements Documents

September 09, 2014 - "White Papers"

Abstract

When beginning a project to create a data acquisition, control, or test system, the main two concerns are often “How can we keep costs low?” and “How quickly will it be up and running?” Unfortunately, that can lead to rushing through the most important first step: the creation of a detailed project requirements document. After years of experience building custom turnkey test machines for a wide range of industries – from automotive to aerospace to energy – Wineman Technology has become well-versed in all the details and questions that must be asked in the early phases of a project. In this white paper, we will discuss the importance of creating the specifications document and critical considerations that should be addressed in the planning process.

wineman technology

Figure 1. Having a clear and precise specifications document is vital to creating a well-organized, smoothly running system.

 

The Importance of Requirements Documentation

Why Take the Time?

When executed correctly, the design process begins with an in-depth investigation to examine the application requirements and to agree upon the project goals. This may involve several meetings between the client and integrator or management and the engineering team to hammer out details, ask more questions, and get additional clarification. It takes valuable time to sit through all those planning and design discussions and produce multiple revisions of the specifications. Therefore, end users may find it tempting to speed through this process and get straight to the execution phase as soon as possible because of tight deadlines. However, a requirements document certainly makes sense if you are hiring an outside vendor to design and build the system because there needs to be an agreement of the specific project goals, process to be followed, and functionality that will be delivered. However, if all the work is being completed in-house, this time-consuming step may seem like unnecessary red tape. After decades of delivering hundreds of custom turnkey systems and assisting engineers with their applications, we have seen how vital a detailed record of specifications is. Rather than being a waste of time, it is in fact a time-saving (and cost-saving) tool in terms of:

  • Establishing project goals
  • Setting expectations and deliverables
  • Planning out purchases, tasks, and resources
  • Ensuring effective communication.
  • Setting up clear lines of responsibility
wineman technology

Figure 2. Take the time to create a detailed requirements document to avoid wasted time, wasted money, and wasted breath.

Delving into the Details

At the beginning of every project, management and the end users (collectively designated as the client) have a vision of the final deliverable that needs to be conveyed to the integration team. At this point in the process, it is important to focus on project goals, features to be included in the system, general design standards, end goals, expected outcomes, and details about the items to be tested.  If similar products are currently being tested, it would also be a good time to document any lessons learned about existing testers, the parts, and test procedures. 

The key is to strike a balance between being too specific versus too generic. For example, rather than insisting on a specific solution that has been used in the past, the client should spend time explaining the pros and cons of any existing solutions or concepts they have, while the integration team should be given the opportunity to apply their experience and recommend new ideas that may satisfy the requirements even more efficiently.  The client can then provide feedback and discuss changes to the integrator’s concepts during a round of revisions. The bottom line is that the specifications document must be detailed enough to clearly define the client’s vision to the integrator, while giving the integrator room to innovate.

Another important item that is often over looked in specifications is, setting up a  process of checks and balances to make sure both parties understand how decisions will be made and what constitutes acceptance both at the end of the project and during critical project milestones.  It is considered a best practice to have one or more design review meetings during the course of a project, each requiring a formal sign off prior to proceeding to the next phase of the project. Ultimately, the requirements document is a way of ensuring that the client and the integrator are both agreeing to a particular process with tracking is in place for measuring progress against the project goals.  We have seen many projects that failed because the integrator agreed to “just get the project done quickly” and failed to follow a good process that included reviews and sign-offs.  In the end the customer did not get what they expected and the cost to fix the system is almost always higher than the cost to do it right the first time. 

Other Uses for Specifications

Not only do the specifications serve as an agreement of deliverables, but it has many other uses and benefits:

  1. The document gives you an objective standard to use for evaluating the proposals received.  As a best practice, integrators should be required to list exceptions to the clients’ specification in a separate section of their quotation so that the client can quickly ensure all vendors are quoting to the same standards.
  2. The specification covers additional, non-technical project deliverables such as manuals, prints, training and other documentation so that the client can ensure that the equipment is supportable after delivery.  These items can often have a significant impact on project cost, so make sure the client’s requirements in this area are clear to the integrator.
  3. The requirements document remains as a standard throughout the entire project to ensure all goals are met.  The original designer may get pulled off the project and another engineering team is asked to step in. Having a record of requirements will be vital to smoothly passing on the work without having to stop and write down all the ideas in the original designer’s head.
  4. For maintenance purposes, the specifications document will list out requirements for spare parts so that the integrator can make sure to quote the spare parts required.
  5. The document can outline the requirements for project management and design review requirements so that the client can ensure the project goals are being addressed prior to delivery of the equipment.

Preparation for the Requirements Documentation

We discussed the importance of creating an in-depth specifications plan with as many details as possible. What does that mean in actually? In the past, clients have produced specifications that range from a blank sheet of paper to a document full of inaccurately defined and incomplete information to reams of boilerplate information that still don’t supply all the necessary data. A well-defined specification may include sections such as:

  • Project goals and objectives
  • Time and cost budget (and plan of action for going over scope)
  • Risk mitigation
  • Design approval process
  • Designation of roles and responsibilities for the client and integrator
  • Tests to execute
  • Cycle time requirements
  • A list of parts to run
  • Part prints or specifications
  • The amount of system flexibility required
  • Measurement and control tolerances required
  • Description of key functions
  • List of channels, alarms, and other parameters
  • Reports required
  • Standards or specific regulations to meet
  • Terms of support and maintenance
  • Outline an acceptance test procedure and time required
  • Lessons learned from any similar testers at your facility 
  • Documentation requirements
  • Training expectations
  • A list of any items that are optional
  • Facilities available for the system (power, air, cooling water, etc.)
  • Signoff on the agreement

By investing time into a well-laid-out, very detailed plan – versus just stating high level objectives and winging it as you go along – you can vet out potential problems or incompatibilities in the design. Without a clear and precise requirements document, the original intent and functionality of the system may get misinterpreted later down the road, especially if the project timeline stretches over a long period of time or the system architecture involves a lot of complex subsystems that must work perfectly together. Furthermore, a project may be worked on by multiple people or teams, so the specifications help keep everyone on the same page for smoother integration.

In the rest of the white paper, we will discuss the main types of requirements that are usually included in a systems specifications document. Use these questions and topics to guide your discussions during the design phase.

Consideration 1: High Level System Goals

While we emphasized the importance of delving into the details of the system, several high level questions will set the tone of the specifications document in terms of the types of questions that will need to be answered. The first things to determine are:

1) What is the goal of the test stand?

There are several major types of test systems, such as:

  • R&D systems that tend to be highly flexible and geared toward high level engineering use
  • Life cycle durability systems that conduct long term testing on the same product or family of products
  • Component design validation (DV) or product validation (PV) to ensure product performance criteria meets the design intent
  • Production test systems for high throughput, go/no go tests

2) Is the system being upgraded or built from scratch?

If the system is being upgraded, how much documentation is there on the current system and does it accurately reflect what really exists today?  Can the client provide enough detailed information about the existing system for someone to quote the upgrade?  Beware if the integrator is willing to quote the job without reviewing the available documentation.

3) How flexible will the system need to be?

Technology is changing at a phenomenal rate and may need to be accounted for in the system definition. Will the unit under test (UUT) stay static or change over time? Does the system need to adapt to a range of different products with minimal effort and additional capital? The lifetime of the tester will also need to be considered.

Remember greater the flexibility and functionality of the test stand, the greater the potential cost or the less likely it is to do everything the client wants extremely well.  For example, a life cycle durability tester is usually a low technology system and does not require a lot of data acquisition or expensive sensors.  Whereas an R&D or end-of-line test system might require very tight measurement tolerances and lots of technology.  Combining those two types of functions together in the same machine, even if they seem similar, may result in less than optimal performance or a higher project budget.

Consideration 2: Hardware

The immediate challenge engineers usually want to address is hardware because it determines so many factors. There is a wide range of criteria when determining hardware for any system, many of which are dependent on the goals of the organization, accepted practices, requirements of the UUT, and how the data is to be handled.

Data Acquisition and Control Hardware

One of the foundational points is the system architecture and its controller. For example, will the system need to be:

  • Real-Time – Determinism (in which certain events must take place at the same time every time without fail) is required
  • PC-Based – Precise execution timing or determinism is not required, and therefore operating systems such as Microsoft Windows may be used
  • Blended – A combination of PC, PLC, or other real-time hardware is used to handle real-time versus non-real-time tasks separately
  • Distributed  – Inputs and outputs need to be placed in a variety of distant locations (from several feet apart to miles apart), yet still be integrated in with a master controller

At Wineman Technology, we highly recommend utilizing commercial off-the-shelf (COTS) equipment whenever possible. By using COTS hardware, you save development time by working with ready-made technology, you build upon the expertise and investment of engineering product manufacturers, and you can receive support if a component doesn’t work or needs replacement.  You can also benefit from future releases of the products to update or upgrade your system.

However, vendor selection is critical when choosing your systems’ hardware. There are a wide range of considerations that can influence the decision, including:

  • Are there company product standardizations to be considered?
  • Is there a frequent need to change or add I/O to the system?
  • Will the system configuration grow or change?
  • How experienced is the integrator with the technology platform?
  • What is the required accuracy of the data?
  • What is the required acquisition rate and type of I/O?
  • Are there requirements for support, serviceability, and calibration?
  • Where is the hardware going to be deployed? What are the environmental conditions?
  • What are the requirements for up time?
  • Are there any physical size limitations or power requirements?
  • Is there a need for custom printed circuit boards (PCBs)? In some cases, there are no COTS products on the marketing that exist to accomplish the task.
  • Can the PCB be replaced with an FPGA chip? FPGAs are reprogrammable. Therefore, if you make a design mistake or need to add new functionality, it may cost significantly less to use the more flexible technology.

Remember the industry best practice of specifying sensors that are typically ten times more accurate than the measurement accuracies required for the pass/fail limits of the part (four times is sufficient in certain cases).  The integrator should specify the accuracy of all sensors quoted. The higher the data rates and the higher the measurement accuracy, the higher the cost usually is.  Make sure not to over specify these numbers.  At Wineman Technology, we have seen many cases when these specifications have caused prices to skyrocket or vendors are unable to quote the project because hardware cannot be found to meet the requirements.

Mechanical Requirements

A properly prepared mechanical requirements specification is integral to your end user’s success. It helps define the performance requirements of the test system’s mechanical elements, materials of construction, fabrication methods and procedures, test and inspection requirements, and so on. In developing a mechanical requirements specification, set bounds on a wide range of relevant parameters for the product or process concerned, such as:

  • Location of test components to toleranced positions and orientations
  • Accuracy of repetitive mechanical motions
  • Durability of motion elements for anticipated life cycle of the test system
  • Proper containment of mechanical energy (speed, torque, static and moment loads, etc.) and balance of forces
  • Application of industry-specific safety factors relevant to the test system requirements

Each of the functions listed above becomes a focus point during the development of a mechanical requirements specification. Important questions to ask during the development of mechanical systems include:

  1. What are the required performance specifications necessary to properly achieve the end result of the product/process test requirements?
  2. How accurately do the process variables need to be controlled and measured?
  3. Does the fixturing or tooling need to be frequently changed?
  4. Does the system require vibration isolation or vibration monitoring for predictive maintenance or alarming?

Mechanical design assembly tools are vital during the design phase to ensure that the mechanical design will stand up to the requirements of the final deployed system. Depending on the data required in this phase, different design and validation tools are available, such as:

  • Computer-aided design (CAD) software
  • Modal, static, rotor dynamics, thermal analysis
  • Laser alignment
  • Portable coordinate measuring machines (CMMs)
  • Vibration analysis
wineman technology
wineman technology

Figure 3. Mechanical design assembly tools are vital in the design phase to ensure that the mechanical design stands up to the system requirements.

 

Electrical Requirements

Electrical considerations also play a significant role into hardware selection and the successful operation of the overall application. A well-detailed set of prints for any equipment built by the integrator should be provided.  Be sure to address the following questions when dealing with your system’s electrical requirements:

  • What are the power requirements for voltage, current, frequency, grounding and electrical noise?
  • The system should be designed for separation of power, signal components, and wire routing for signal integrity purposes. How will AC and DC lines be isolated?
  • Is a panel required to handle a specified amount of spares?
  • Who will handle the system installation and equipment removal? Are there any special installation requirements?  
  • If the project requires retrofitting a system, what components will be reused? What documentation is available, and how will risk and warranty be managed?  
  • What are the troubleshooting and maintenance requirements (including documentation)? Are all wires and major components labeled for easy identification and troubleshooting?
  • Is there any standard component list that needs to be followed for common electrical components?
  • How often will the electrical connectors be inserted into or disconnected from the UUT?

Facility Requirements

The system itself usually resides within an indoor facility. Therefore, the facility layout, available utilities, and the limitations of the existing space must be taken into consideration. The following considerations are examples of requirements that may be affected by the facility’s parameters:

  • Is there adequate electrical power available to the tester?
  • What is the power quality like in the plant?  Are there brownouts or noise on the power lines?  Does the system need to include an isolation transformer, UPS or other power conditioning equipment?  Does the area for the test cell have a good ground?
  • What are the environmental requirements of the system? Does the enclosure need heating or cooling, viewing ports or windows, or access ports?
  • How far are the wiring runs and how large is the cable bundle? How will the power be separated from the signal wiring?
  • What is the required sensitivity accuracy of the measurements? Are there hardware items in the facility that may induce noise into the system?
  • What is the location and placement of integrated subsystems?
  • Are any other facilities required (e.g. compressed air, cooling water, hydraulic fluid, etc.)?
  • Is fuel is required, and if so, is a fuel farm needed?
wineman technology

Figure 4. The facility’s layout, utilities, and other features may impact the equipment definition.

Safety Requirements

Lastly but most importantly in the hardware considerations is safety – both from the standpoint of personnel safety as well as safety of the equipment and UUT. This would include following the standards set by various governing bodies for Health and Safety (OSHA), Electric Code (NEC) and Fire Protection (NFPA).  Below is a sample list of common safety measures:

  • Guarding for components that have rotational aspects or pinch points
  • Emergency stop (e-stop) or kill switch
  • Fire suppression (NFPA)
  • Hardwired interlocks and safeties (such as door interlocks)
  • Procedures for different shutdown requirements
  • Lock-out or tag-out requirements
  • Sound attenuation
  • High pressure fluid for zero potential energy
  • Protection against hazardous gases or fluids
  • Fluid containment
  • Local codes and requirements

Consideration 3: Software

Ultimately, the software is the heart and soul of the system. It provides a host of capabilities, such as the user interface, monitoring, test profile generation, and control set-up. A best practice is to standardize software platform that natively integrates with or has available drivers for all the hardware components, their calibration utilities, and communication protocols. Depending on the system’s needs, find out if the software can give you access to low level API to allow integration of non-supported devices, custom communication protocols, FPGAs,  control models, and other custom features. However, in the interest of ease of use, the final deployment software should not force the end user to make changes by accessing source code but rather through a menu-based environment.

In terms of long-term accuracy, are calibration utilities available or will they need to be developed from ground up? In order to extend the lifetime of the system, make sure there is the appropriate functionality and advanced programming features to ensure scalability, support, and long-term compatibility.

In the end – whether you are coding in C, LabVIEW, or a COTS-based software tool – if the day-to-day users of the application are happy with the software interface, flexibility, stability, intuitiveness, and functionality of the system, most other issues can be overcome. In other words, if the operators don’t like the system, the project won’t be a success.

wineman technology

Figure x. Functionality, stability, usability, and compatibility with the hardware and other integrated subsystems are all important factors for the software development.

Data Management and Reporting Requirements

As part of the software requirements, you must decide what to do with the system’s data, in terms of data management, reporting, storage, and accessibility. Below are a list of questions to consider when developing the software:

  • Data Storage: How much data needs to be maintained on the test system? Will this information need to be mined over time? Will this system require long term data storage or integration with plant systems?
  • Data Management: What functionality is needed in terms analysis, data mining, scripting, and report generation?
  • Reporting: Do specific data types and file formats need to be supported? Will the data be exported into another software such as Microsoft Excel or NI DIAdem for further analysis?
  • Remote Access: Will end users need the ability to remotely check-up on the system status, respond to alarm conditions, or view data? Varying amounts of access can be provided via cellular contact, website browsers, or other communication methods.

Execution of the Requirements Documentation

Once the requirements document has been created, now you must make sure the specifications are carried out effectively and intelligently. How the design cycle of the system is managed can significantly impact the success rate of the final deliverable. Here are some best practices in project management to follow during the design cycle:

  1. Once you have a technical specification, the development process needs to be agreed upon so that both the client and integrator can be assured that the technical objectives of the project are getting met. 
  2. The project management process will determine factors such as project management software, meeting locations, a realistic delivery schedule, and design gates that ensure the project is being executed correctly. At subsequent design review meetings and approvals, this process serves to outline a reasonable set of expectations for both parties.
  3. The integrator should be prepared to provide design documentation in these review meetings that have enough detail so that the client can determine if their needs are getting met. 
  4. The client should be prepared to carefully review documents and make sure the integrator is following the vision outlined in the specification. 
  5. The process should include tracking of milestones and deliverables. It should also define who has the authority within your organization to make decisions if changes or approval is needed. 
wineman technology

Figure x. Wineman Technology provides review requirements and check-off lists for different stages in the design cycle.

In conclusion, the specifications document is all about “measuring twice and cutting once.” By spending the time upfront to plan out all the details of a system before execution, fewer mistakes will be made. With a detailed list of requirements, ultimately the final system will be closer to the original vision, ensuring a successful usage of time and resources.
 

Need Help with Requirements Documents?

Wineman Technology has years of experience creating specifications that become successful systems. For help building a comprehensive requirements document for your test and control applications, contact us today. 

 

Move to Top