This is the sixth in a series of blog postings in which we present a top-ten list of common errors encountered in the context of medical projects. Of course, such a ranking depends on personal observations and individual experience – and hence has a subjective outcome. Please feel invited to tell us about your perspective in the comments section!
Documentation arguably constitutes one of the most dreaded aspects of medical projects. From a theoretical perspective, this is surprising: The laws and standards only require documentation that is useful to have, anyway. After all, proper documents that focus on the right things are extremely helpful – be it for developers, testers, auditors, or anybody else. So why is documenting such a hassle in many projects?
Unfortunately, there are several factors that can ruin both the process and the result of all documentation in a project. In today’s posting, we concentrate on a true classic – one that is less obvious first, and thus especially dangerous. Let’s face it without further ado: Many projects are established without a proper documentation concept. In particular, many projects fail to define adequate structures for their requirements.
At first glance, one might believe that a poor structure for requirements is a local problem: Maybe the requirements engineer won’t have much fun maintaining the requirements specifications – so what? Well, the truth is simple: requirements affect everything. They constitute critical input to all other disciplines: analysis, architecture, design, implementation, testing, and what not. Therefore, a poor requirements structure automatically implies a lot of patchwork on the left side of the V model, and perfect chaos on its right side as well. This effect can manifest in different forms, so let us consider some examples:
- Requirements documents are usually treated more formally than design documents. Hence, people are tempted to maintain only abstract top-level requirements in the former and to disguise all other requirements as design decisions (which are then documented in the latter). This can become a terrible problem because most projects define entirely different testing approaches for requirements versus design decisions.
- Analogously, it is a bad idea to maintain low-level technical constraints in high-level requirements specifications. Imagine a top-level user requirement stating that the software shall protect all patient records it keeps in RAM using a cyclic redundancy check. How on Earth would you verify this by means of a system test?
- Large system projects necessarily demand a requirements breakdown. For example, you could trace from user requirements to system requirements, and from system requirements to mechanics/electronics/software requirements. Again, and for similar reasons as outlined above, placing a requirement wrongly in this structure can make it virtually untestable.
On a side note, there are entirely different kinds of factors that lead to bad documentation. One of my favorite examples is when the documentation tool landscape is dictated by people who don’t have to write a single page of documentation throughout the entire lifecycle. As a consequence, the choice of tools is optimized for ancillary aspects (e.g., as little work for the IT department as possible). The actual core tasks, namely writing and maintaining documents on non-trivial matters, then easily become such a royal pain that the natural outcome can only be… terrible specifications.
Alas, matters get only worse from here: Bad documentation is a self-energizing effect. As team members face insufficient and outdated documentation when they need to look something up, they get used to finding out the truth by other means, thus often losing the motivation to keep their own documents in order.
Coming up next: #4, Risk Analysis Gone Wrong. See you there!
- Top Ten Errors in Medical Projects – #6: As Low As Reasonably Practicable
- Top Ten Errors in Medical Projects – #7: The 100% Confusion
- Top Ten Errors in Medical Projects – #8: Eager Beaver / Lazy Bu
- Top Ten Errors in Medical Projects – #9: Process versus Project
- Top Ten Errors in Medical Projects – #10: Clinical Something!