Model documentation in the eye of the beholder: Lessons learned from a flood risk model for a dike in the Netherlands

Computer models are essential for flood risk decision-making, where documentation plays a key role in ensuring transparency and reproducibility. This study examined how different stakeholders perceive documentation practices by analysing a Dutch flood-risk model case study. We assessed perspectives from external observers (ourselves), the modellers (a consultancy company), and the model end-users (the Water Authority) through documentation analysis, model reruns, and interviews. We found a mismatch between the Water Authority’s documentation goals and what was achieved with the delivered documentation. For instance, we could not reproduce the model results based on the available documentation, as crucial tacit knowledge remained implicit. Despite these shortcomings, both the consultancy company and the Water Authority were satisfied with the final products — illustrating how documentation quality is in the eye of the beholder and in this case shaped by the trust from the Water Authority in the consultancy company. However, when key goals like transparency and reproducibility are not met, accountability for model results becomes a concern, especially in decision-making contexts — highlighting the gap between perceived adequacy and broader expectations of documentation.