The word "documentation" immediately makes many people recoil. Creating, reading, or searching for documentation is usually not a particularly enjoyable activity. Yet documentation is necessary and important. The goal is to reduce the effort required for a project with documentation than without. If you were to work faster without documentation, why bother with the work at all? The goal of documentation is to capture decisions and make them visible. Documentation is therefore a tool that serves as a guide, a record, and a basis for discussion. For documentation to be effective, a few requirements must be met. I would like to present these in this article.
|
|
| Dipl.-Ing. Goran Madzar, Partner, Senior Systems Engineer E-mail: madzar@medtech-ingenieur.de Phone: +49 9131 691 240 |
|
Do you need support with the development of your medical device? We're happy to help! MEDtech Ingenieur GmbH offers hardware development, software development, systems engineering, mechanical development, and consulting services from a single source. Contact us. |
|
| Requirement | Explanation |
| Helpful | A document must be useful. If the document isn't helpful to anyone, it's not needed. |
| Correctly | Incorrect information is worse than no information. Therefore, it is important to ensure that documentation is accurate. Errors in documents lead to a rapid decline in trust in the documentation, thus diminishing the overall value of the documentation. Therefore, accuracy is the top priority. |
| Current | Documentation ages, and with it, documents can become out of date. What was correct yesterday may already be incorrect today. Therefore, it's important to nurture and maintain documentation. |
| Easy to use | It must be easy for consumers to find and use the document. Fixed structures and conventions can be helpful in this regard. |
| Easy to understand | Facts, facts, facts, and think about the reader! This slogan also applies to documentation. When creating documentation, you have to think about the reader. What information do they need and what language do they understand? How can I, as the creator, present the material in a way that is understandable to the reader? |
| Easily changeable | The easier it is to change documents, the more likely it is that documents will actually be adapted and maintained. |
| Short | Less is more. Because no one reads documents that are too long, and thus they miss their goal. It's not about writing novels, but about documenting the important information. |
| Versioned | A document must have a version. This allows different versions of the same document to be distinguished. Ideally, you can manage the different versions using a version control system. |
| Responsible | Every document has an owner who is responsible for the document and who is responsible for its maintenance. |
| Top-down organized | It should be possible for the reader to read the matter starting from a high level of abstraction with few details, step by step until it is refined with more details. |
| Explanatory | |
| Free of redundancy | The aim should be to document information in only one place. Redundancy leads to the risk of contradictions and is unsuitable for documentation maintenance. Information can only be used redundantly if the information at that location is necessary for the reader's understanding. |
| Nice | If documents, please make sure they're well formatted and free of spelling mistakes. The documentation should be worth the extra effort. |
| Clearly | Terms and representations should be used clearly. A glossary should define the terms. Illustrations and diagrams should be explained if they leave room for interpretation. |
Develop a positive attitude toward documentation so that it's not seen as a chore, but as an integral part of the work process. Always include documentation in the "definition of done" of a work package. And be aware that you're documenting for the reader, not the author.
Best regards
Goran Madzar
Written by Goran Madzar
More articles
Writing requirements is an integral part of any product development. Only when you know what the product is supposed to do can you design it accordingly and ultimately test it. ...
To ensure high product quality and customer satisfaction, quality problems must be identified, analyzed, and resolved early. CAPA is a proven tool to help companies ...
Are you familiar with batteries and accumulators? The livestream "Keysight: Live from the Lab" provides a good introduction to the topic. In this livestream series, hosted by Keysight, ...