In many long-running projects or long-lasting systems corresponding documentation sooner or later becomes outdated in a significant degree. In agile approaches this is often even worse due to the common and unfortunate misconception that agile development does not need documentation.
The reason for outdated information lies within the many frequent changes. While directly changed parts are more likely to be kept up-to-date, for indirectly impacted parts this is less likely so. To keep documentation up-to-date, we need to take care of those indirect impacts.
We use model-driven documentation combined with tracing and design-implement-test loops to keep our system documentation up-to-date. The underlying meta model is based on UML and a DSL. This DSL, a domain-specific language, combines elements from TOGAF and customizations from projects at several clients.
After a brief introduction to model-driven documentation, we present the experiences gained over the last couple of years. These experiences originated in the automotive industry for classic IT like marketing applications. The approach has then been generalized for Automotive Engineering, Wealth Management and others. It can be used on several abstraction levels like enterprise, project and system architecture.
Following aspects will be discussed:
- Why does documentation become outdated?
- How can model-driven documentation be used to keep system documentation up-to-date?
- What is the benefit of model-driven documentation for requirements managers & analysts, developers and testers?
- What are the limitations of model-driven documentation?
We also present best practices and how to continuously improve, and give an outlook on tool integration activities that help to detect outdated documentation earlier and feed up-to-date information directly back into the documentation.
Dr. Udo Nink is freelancer at Dr. Nink IT Consulting.
Udo has 20 years' experience in IT consulting. He focuses on Enterprise Architecture, IT Architecture, Method Engineering and Tool Integration. He had challenging projects at well -
known customers in industries like automotive, financials, telecommunications, logistics, quality assurance, and public sector.
Prior to that Udo co-founded a software development company, managed product development for a component framework, and was Principal Consultant with Oracle
Udo holds a doctor's degree in engineering and a diploma in computer science both from Database and Information Systems Group of Prof. Dr. Theo Härder, Department of Computer
Science at University of Kaiserslautern.