Building a successful system requires a process. Within the process, there are many issues that must be addressed.
Having a defined process in place is fundamental to building a successful system. Although there is no set of rules governing what the process should be, it should define how a company or project builds systems. A process may vary within a company depending on the size of a project, but even with the deviation, part of the process should identify the steps taken for the deviation. Without having a process, a team cannot be identified to build the system. The process identifies the documents that are produced, the order in which the documents are produced, the content of the documents, the company area responsible for producing the documents, etc. My successful projects are those where a supported process was in place when I arrived, or those that I had management support in implementing a process. Part of the process is having a set of company standards.
Although we call them standards, they are conventions that if followed will provide consistency. Many times we hear a vendor claim to follow a standard when in fact, they add extensions or modifications to the standard making them inconsistent with trusted vendors that adhere to the standard. A vendor that adds or modifies a standard is not standard compliant since they do not follow the conventions that were agreed upon. Companies also have internal standards, and projects tailor the company standards to fit the size of the project system.
Part of project planning is organizing a set of standards that will be used on a system. These standards include naming conventions, outlines for documentation, types of documentation, to name just a few. No two projects are identical, so even though I may have company standards, they are tailored to the project.
I normally include references to or copies of templates for software requirements, high level design, data description, data definition, and detailed design in the standards document for each project I am responsible for.
A system may be built to fill a need, or because there is a potential market for it. As an engineer, I may see a need for a tool to make my job easier. This is the easiest system to build, since, I know the requirements. Because I am the customer, user, and builder, the sign-off is usually skipped, also, because most companies do not see the need for development tools to make my job easier, I usually have to do the work at home without pay. Actually, the reward comes in the form of a good reputation.
Much of my experience is with DOD projects where there is no market analysis required. The customer had a need, and the companies that I worked for knew that I could design and build the product. Even in these projects, I found it necessary to maintain dialogs with the customer to determine what was really wanted. Engineers seem to speak a different language than normal people, so the more time we spend trying to communicate with our customers, the more we understand our customers needs.
It is very important to develop a schedule for any system that is worth building. Actually I usually do a preliminary schedule, then once the requirements are complete, I do a development and delivery schedule. The preliminary schedule helps to view the scope of the system prior to developing the requirements. The development and delivery schedule identifies the specific goals that must be met. Beware, the tools used for scheduling are only as good as the person creating the data.
A schedule should be realistic and identify critical paths. It is best if previous project tracking data is used to develop a schedule.
It is extremely important to track a project. If for some unforeseen reason, a milestone is missed, the reason for missing it should be documented; not to point the blame, but to use the information for planning future projects. By tracking each step of all projects, information can be collected to make scheduling of future projects more realistic and achievable.
The system specification document describes the system and gives a high-level view of what functionality the system will provide. This is the document that provides the overview of the integrated system. The system specification is the guide that will allow the derivation of the hardware, software and test requirements. If the system will be receiving data from external systems, or if it is to provide data to external system, the data is described or referenced in the system specification.
System requirements are an expanded breakdown of the system specification. The system requirements consist of hardware requirements, software requirements, and a hardware / software interface specification and may include a user interface specification.
The hardware requirements describe the functionality that any special hardware provides. My role in hardware requirements for new hardware is limited to requesting status words and special commands to access the status. I may also request the order or grouping of status bits to make implementation more efficient.
The software requirements describe the functionality that the software must provide. I have used a tailored 2167-A, but prefer a tailored IEEE Software Requirements Specification guideline. I am happy to see that the DOD has dropped 2167-A and is moving to the new universal IEEE standards. I have created a tailored template for the IEEE specification as well as conventions for using the template. Using a template and adhering to conventions allows the use of a tool (I call it a Shall-Plucker) to extract the requirements and creating a cross reference that can be used to find conflicting or missing requirements.
The interface document contains the data that describes how the software and hardware communicate. Although the names may vary, it contains but is not limited to:
This document describes the types of testing and the data ranges. There should be separate sections for bench tests, and for field tests.
This step is most successful when the documentation is supplied to the participants at least a week before the review. Although rare, if there are extensive changes as the result of the review, a follow up review should be scheduled after the changes are incorporated. If the changes are minor, the document should be updated as soon as possible, and all authorized participants sign the acceptance.
From the time the requirement acceptance is signed, until the system is built, there should be no further changes to the requirements. Any changes will cause schedule impacts; even small changes add up to delay the final system. Desired changes should not be ignored. They should be filed and saved until after initial system is built, then reviewed to determine the requirements that will be added to the system. It is important that the engineers designing the system have access to the file of add-on requirements that are being collected while building the system, as the knowledge of future requirements can help prevent designing out a requirement.
Once the requirements are complete, they are analyzed for completeness, correctness and reality. Even though this is listed after requirements review, it should be started long before requirements review. A requirement that cannot be implemented can cause problems. A requirement that cannot be tested can also cause serious problems. The most successful systems I have been associated with involved software, hardware, and test taking part in the requirements definition.
This step is part of high level design, but because of its importance, I address it separately. This provides a separate document where the data is described. Any system that uses software, is a data mover. It is important that the data be understood prior to any attempt to design a system.
I view high level design as the overview of the entire system from a software perspective. The high level design provides a systematic decomposition of the system functions and shows how they are collected in tasks or modules and how they communicate with each other. The high level design can be mapped directly to the software requirements specification. When I design a system, I require that the high level design reference the paragraphs in the requirement specification that are satisfied for each function, module, or task.
Part of high level design is a refinement to the schedule. This refined schedule shows how the pieces of the system are going to be integrated. It shows dependencies between modules, and modules that can be integrated at any time since they have no dependencies.
This review usually involves the same participants that did the requirements review. My role at this review is to defend my design, show that all the requirements are met, and explain the design trade-offs that were considered that drove our design.
This document requires the hardware/software interface specification, the data description, and the high level design. This document details the big-little endian incompatibilities and how they are resolved. It describes the sizes and ranges for the data that is passed about or collected by the system. This document contains references to the paragraphs in the parent documents from which they were derived.
I view detailed design as the last critical step before coding begins. Depending on the budget, and tools available, I may require the use of a template using structured english, or the use of an expensive tool that will provide graphic detailed design. I find that many of the GUI tools are more of a hindrance when doing a design since more time is spent learning how to use the tool than is spent thinking about the design.
I normally require that configuration control is in place before detailed design begins, and have each engineer check out and check in the documentation they are responsible for each day, keeping the system configuration up to date.
Many young engineers are just out of school, so by using configuration management to view the progress of the detailed design, I can see potential deviations, oversights, or sometimes even errors, and provide guidance early in the process.
The participants in a detailed design vary. I normally invite members of test, system engineering, customer representatives, and technical leads from other projects. I will emphasize that the review is to determine if the design will meet the requirements and conform the the high level design. It is not the time to have a better way.
On my projects, I normally require a unit test description for each module, method, or function in the detailed design. It is important that software engineers think about how they are going to test a component as they are designing it. This step saves a lot of headaches later on.
With a good detailed design and the data definition document, code is a mechanical operation. Using the test descriptions written during detailed design, the unit test eliminates bugs at the low level before integration test begins.
I like to begin integration with an entire system composed of stubs. The schedule identifies the order in which the stubs are replaced. For systems where I have implemented the operating system, or have the source for the operating system, I will add code to the operating system using compiler directives. By using a special operating system for doing system test, I can verify that the correct paths were taken. My process requires that the tests are re-run on an unaltered operating system, but it is well worth the extra effort when problems are encountered.