Over the years I have learned that there are no assurances for a successful development process, but having said that the majority of the successful ones had two steps in the development’s early stages that were carried out thoroughly and thoughtfully: System-Market characterization and early System Requirements. In this part of this post series, we will concentrate our efforts on the latter and more specifically formulating System Requirements. Obviously, the examples will not be fully-blown System Requirements since that would, without a doubt, be both tedious in writing and tiresome in reading.
If you have not yet read the first and second posts in this series I strongly recommend that you do however, this post may be read standalone leaving an understanding gap of the top-level design process.
This System Requirements part in this post series is very long hence it is divided into two posts – the first is dedicated to the requirements themselves and how to write them and the second and shorter post details the correlation between the requirements and requirement hierarchy.
The Correct Way to Write Requirements
When it comes to requirements in general and System Requirements in particular there is a correct way and a wrong way to have the requirements written.
A checklist for a correctly written requirement is nicely detailed in this NASA page. It may be summarized in one short sentence:
A requirement must be clear, concise, unambiguous and verifiable.
That seems simple enough. Anybody can write something in that manner. So where do things get complicated?
First, clear is very subjective. One way to verify “clear” is to give the written requirement to someone who has not seen the text before and who has no prior knowledge as to the project and who does not belong to the same technical field. If that someone gets it right, the requirement is probably clear. This also goes for unambiguous.
Second, especially in System Requirements, the different stages in the development process need different kinds of certainty levels. When everything is already set in the plan and we know for sure the details of the architecture this is easy enough. However, when introducing the initial requirements, the requirements need to convey the message (technically of course) but not limiting the engineering into a specific solution. This task is very tricky! For example, if we wanted “feedback\control over a laser intensity” and we formulate it simply as is there are at least two methods that immediately come into mind: feedback the laser current electronically or feedback the actual laser intensity via an optical power meter – online or offline. But, if we formulate it as “feedback\control mechanism for laser intensity to keep the actual laser intensity inside a +/-0.2% of the requested intensity level during operation”, in this particular case we will still have multiple methods to implement this control but we have quantified the solution margins. BTW, in the requirement comments we should define how to test “actual laser intensity” – what method and which tooling, otherwise “actual” does not have a technical meaning.
A requirement without a verification method is meaningless
Third, verifiable means that there must be a way to test if indeed there is compliance with the requirement. We may not possess the capabilities to test the requirement fulfilment and it may need to go to a 3rd-party laboratory or an external vendor, but there is a way to verify it. It is better of course to have the verifying method in-house and as simple as possible.
Fourth, as stated before, the further along we go in the development process our ability to fine-tune our requirements is better. That does not mean that the initial requirement is incorrect or needs to be changed but it may mean that an additional requirement should be added. For example, if proof-of-concept activities already showed that a power meter would be the optimal choice for the system, the requirements can be added with a sub-requirement “the feedback shall be power meter based”.
Note that this is a matter of company document structure and hierarchy – there are companies that keep the System Requirements document in a very high level and such lower-level requirements or amendments are transferred to other requirements documents in the hierarchy. I personally like to have all system-level requirements in one place because it is then easier to follow and maintain but, in this case, there is no right or wrong. Only make sure that when derivative requirements appear in different documents have them changed and updated together. One thing that you don’t do, – you do not keep the exact same requirement in two different documents. Such redundancy is dangerous.
Fifth and last, re-design because the market has changed is a part of life’s necessities however, re-design because a requirement was misunderstood or was malformed is a mistake that we can and should avoid.
Metal Cutting Laser Machine Example
To remind you all, this is where we left our top-level go-to block diagram:
Since we are in the earliest stage of our development, we have to keep the requirements on the one hand free from technical bias of the solution while on the other hand clear and accurate.
For ease or reading, I have created an example System Requirement document with the different sections mentioned further down this post. Obviously, this requirements document is far from complete, it only illustrates examples of how to write the requirements and their respective relations. Note that I cannot guarantee that all the numeric requirements written there are indeed realistic (especially the optical resolution and DOF) – I haven’t gone that far with this example.
General
Always have date, revision number and author in a System Requirements document and try as best as possible to accurately describe what has changed since the last version.
This is also the place to insert all the “dry” document data required by the organization – table of contents, tables of figures and tables, related documents, related projects, documentation numbers and favorite pets 
. Anything that is required for proper documentation.
Background
Writing a background section in a requirements document is not an “official must” however, when someone reads the document this background section assists in getting that person updated of the project’s objectives and all the non-official descriptions to explain in normal words what we came here to do.
It is also good practice to insert all the block diagrams and top-level flow charts in this part, even if they are referred to in the actual requirements themselves.
This is also the place to mention where the product is at compared to other products of the company (if relevant) – this is very valuable information – it tells the reader where the technical overlaps with other projects are, if any.
Performance
This is one of the most important parts of the document, one that I strongly suggest you take special care when formulating. Any change that may occur down the road in the development process in this performance section may drive major changes in design and the cost of each misunderstanding in the section can be a project killer.
Performance requirements are in many cases a direct translation of the Product Requirements and in our example, the technical content of this post.
Architecture, Functionality & Flows
Just as we had to explain to ourselves what the architecture is and what its building blocks are, we have to specify it correctly in the requirements document. It is important to specify each block’s functionality in a way that any implementation chosen will comply with that functionality and we wouldn’t have to refine the specifications such that there will be a re-design.
And finally, we are required to specify the flow of events, data, material, error handling and so on in our system. This tells the relevant technical disciplines where to intervene and address the solution at their end.
Those of us System Engineers that manage in the early stages of development to squeeze in the system flows and also the expected Service Strategy and Manufacturing Methodology deserve their spot in heaven. Figuring out service and manufacturing limitations in the architecture stage saves a lot of effort and money when advancing along the project development.
External Interfaces
External interfaces impact the Product and therefore must be derived from the Product Requirements or their derivatives as we have witnessed in this post. So, the System Requirement document must include each of the interfaces discussed in the interface section in the second post in this series.
Note that in our example there are a few optional requirements which were discussed that would be decided upon later. It is important to comment when the optional requirement is going to be resolved i.e. turn into an official requirement or completely removed from the requirement document.
Internal Interfaces
When specifying the internal interfaces, we should separate two stages in the development process: the initial stage where we are at right now where the connectivity between the different components and sub-modules is not as yet decided upon and when we already have an internal comms and interfacing architecture and configuration. In the first case we must specify the magnitude and content of the communications and the functionality of the interface (if not comms) while in the latter we shall specify the little details of the interface.
Design Guidelines
This is where we insert know-hows as well as requests that are either non-verifiable or cannot be formulated as a proper requirement but have impact over the technical implementation of the system. For example, these could be a request to use off-the-shelf (OTS) products as much as possible (which definitely cannot be a requirement: would you stop development if you have a single item that is not OTS in your design?); a request to re-use code base or HW base from previous or parallel projects as required; refrain from using open-source SW libraries and so on.
Future Features
This section is not a must but it can save a lot of pain and headache in future projects. If we know already now in our project that the next project will have a certain feature, we may be able to give a heads-up to the engineering team that if a certain architecture may accommodate both generations’ feature it could shift the architecture in a certain way.
For example, if we know that 4GB MEM hardware is sufficient for our current project but 8GB is required for the next-gen project and the 8GB MEM hardware is a completely different hardware architecture it is wiser to choose the 8GB over the 4GB only for not changing the whole hardware when starting next gen development.
One important caveat: do not sacrifice the current product timeline or budget for future projects in any way – the objective is to develop the current project successfully otherwise we may not reach the future project.
I must emphasize that communication within the team is more important than the correctness of the requirements documents. When the team works in transparency and is coordinated at all times even if the requirements are not so well formed the results are expected to be very good, that is much better than the results of a perfectly written requirements document that was poorly communicated to the team.
This is where we stop for this post. In this post we have covered the requirements and the different topics we must cover in our requirements document. In our next post we will detail with what is requirement hierarchy, why it is important and what are the System Engineering best practices to evolve the requirements such that indeed nothing is left behind.