The documentation of design decisions in engineering projects: A study in infrastructure development

In most design projects, the documentation of design decisions is considered important. Among others, documentation of design decisions contributes to the traceability of decisions that shape a project’s development process, helps deal with changes in the project and prevents the recurrence of old discussions. Yet, little attention is given to documenting design decisions in civil engineering literature. In this study, a theoretical framework for the key elements of this documentation process was developed. Four road infrastructure projects were studied and compared to this framework by means of pattern matching. This method compares theoretical and empirical patterns and determines whether they match or do not match. The findings demonstrate that accessibility of documentation for all involved project parties and division of documentation tasks are in accordance with literature. However, the documentation of design decisions and their rationale is not done as completely as is recommended in theory. Literature states that the documentation of interrelations and context of decisions should be described thoroughly, but that is barely done in practice. In addition, the findings show that neither immediate documentation, nor periodical monitoring of documentation is applied. Based on these findings, this research proposes a strategy for improving the documentation of design decisions

The documentation of design decisions in engineering projects:A study in infrastructure development

In most design projects, the documentation of design decisions is considered important. Among others, documentation of design decisions contributes to the traceability of decisions that shape a project’s development process, helps deal with changes in the project and prevents the recurrence of old discussions. Yet, little attention is given to documenting design decisions in civil engineering literature. In this study, a theoretical framework for the key elements of this documentation process was developed. Four road infrastructure projects were studied and compared to this framework by means of pattern matching. This method compares theoretical and empirical patterns and determines whether they match or do not match. The findings demonstrate that accessibility of documentation for all involved project parties and division of documentation tasks are in accordance with literature. However, the documentation of design decisions and their rationale is not done as completely as is recommended in theory. Literature states that the documentation of interrelations and context of decisions should be described thoroughly, but that is barely done in practice. In addition, the findings show that neither immediate documentation, nor periodical monitoring of documentation is applied. Based on these findings, this research proposes a strategy for improving the documentation of design decisions.</p

Software Sustainability: Research and Practice from a Software Architecture Viewpoint

Context: Modern societies are highly dependent on complex, large-scale, software-intensive systems that increasingly operate within an environment of continuous availability, which is challenging to maintain and evolve in response to the inevitable changes in stakeholder goals and requirements of the system. Software architectures are the foundation of any software system and provide a mechanism for reasoning about core software quality requirements. Their sustainability – the capacity to endure in changing environments – is a critical concern for software architecture research and practice. Problem: Accidental software complexity accrues both naturally and gradually over time as part of the overall software design and development process. From a software architecture perspective, this allows several issues to overlap including, but not limited to: the accumulation of technical debt design decisions of individual components and systems leading to coupling and cohesion issues; the application of tacit architectural knowledge resulting in unsystematic and undocumented design decisions; architectural knowledge vaporisation of design choices and the continued ability of the organization to understand the architecture of its systems; sustainability debt and the broader cumulative effects of flawed architectural design choices over time resulting in code smells, architectural brittleness, erosion, and drift, which ultimately lead to decay and software death. Sustainable software architectures are required to evolve over the entire lifecycle of the system from initial design inception to end-of-life to achieve efficient and effective maintenance and evolutionary change. Method: This article outlines general principles and perspectives on sustainability with regards to software systems to provide a context and terminology for framing the discourse on software architectures and sustainability. Focusing on the capacity of software architectures and architectural design choices to endure over time, it highlights some of the recent research trends and approaches with regards to explicitly addressing sustainability in the context of software architectures. Contribution: The principal aim of this article is to provide a foundation and roadmap of emerging research themes in the area of sustainable software architectures highlighting recent trends, and open issues and research challenges

A mapping study on documentation in Continuous Software Development

Context: With an increase in Agile, Lean, and DevOps software methodologies over the last years (collectively referred to as Continuous Software Development (CSD)), we have observed that documentation is often poor. Objective: This work aims at collecting studies on documentation challenges, documentation practices, and tools that can support documentation in CSD. Method: A systematic mapping study was conducted to identify and analyze research on documentation in CSD, covering publications between 2001 and 2019. Results: A total of 63 studies were selected. We found 40 studies related to documentation practices and challenges, and 23 studies related to tools used in CSD. The challenges include: informal documentation is hard to understand, documentation is considered as waste, productivity is measured by working software only, documentation is out-of-sync with the software and there is a short-term focus. The practices include: non-written and informal communication, the usage of development artifacts for documentation, and the use of architecture frameworks. We also made an inventory of numerous tools that can be used for documentation purposes in CSD. Overall, we recommend the usage of executable documentation, modern tools and technologies to retrieve information and transform it into documentation, and the practice of minimal documentation upfront combined with detailed design for knowledge transfer afterwards. Conclusion: It is of paramount importance to increase the quantity and quality of documentation in CSD. While this remains challenging, practitioners will benefit from applying the identified practices and tools in order to mitigate the stated challenges

Synchronisation eingebetteter Architekturentscheidungen mit Architekturentscheidungsprogrammen

Diese Arbeit behandelt das Thema der Synchronisation von quellcode-intern und quellcodeextern dokumentierten Softwarearchitekturentscheidungen. Einerseits gibt eine Java-Annotation, welche es erlaubt Architekturentscheidungen im Java-Quellcode zu hinterlegen, andererseits können Architekturentscheidungen auch mit dem Modellierungswerkzeug AD-Mentor modelliert und in einem Versionierungsrepository hinterlegt werden. Da Architekturentscheidungen somit an verschiedenen Stellen dokumentiert werden können, ist es sinnvoll diese zu synchronisieren. In dieser Arbeit wird ein Konzept zur Synchronisation von eingebettete Architekturentscheidungen mit modellierten Architekturentscheidungen anhand eines Versionierungsrepository vorgestellt und implementiert. Zur Verifikation des erstellten Konzepts wurde eine Fallstudie anhand des implementierten Synchronisationsprogramms durchgeführt und ausgewertet

La arquitectura sostenible como estrategia de la habitabilidad en el Asentamiento Humano Grano De Oro, Pucusana 2023

Esta investigación planteó como objetivo general analizar cómo la arquitectura sostenible puede mejorar las condiciones habitacionales en el asentamiento humano Grano de Oro en Pucusana. Se utilizó un enfoque cualitativo con diseño fenomenológico. Se emplearon fundamentos teóricos que destacaron la importancia de la arquitectura sostenible ya que genera un impacto positivo al ahorrar recursos y materiales, y mejorar el confort, beneficiando tanto al medio ambiente como a los habitantes, como lo planteó Soriano (2021). Además, da Silva y Gonçalves (2020) enfatizaron que considerar dimensiones espaciales, una distribución adecuada y el acceso a recursos necesarios son clave para alcanzar una correcta habitabilidad. En este estudio participaron 3 especialistas en el tema y se analizaron 10 inmuebles. Para recopilar la información, se utilizaron instrumentos como la guía de entrevista semiestructurada con 15 ítems y 30 fichas de observación; estos fueron validados por 3 expertos docentes. En los resultados, se vio que los teóricos y participantes estuvieron de acuerdo con que la bioarquitectura es una gran medida para una adecuada habitabilidad. Se pudo concluir que la arquitectura sostenible hoy en día contribuye significativamente en crear espacios habitables a largo plazo pues genera armonía con el entorno natural y brindar confort a los habitantes

Considerations for the interdisciplinary development of environmental system models

Effective decision making and policy development requires holistic consideration of the modelling context. This thesis explores how consideration of multiple disciplinary perspectives and concerns lead to an integrative model development process for the purpose of socio-environmental systems (SES) management. The research is presented through two frames: (1) Integrated Environmental Model (IEM) development through a System-of-Systems (SoS) approach, and (2) the socio-technical considerations within an interdisciplinary modelling process. The presented research incorporates the perspectives of the modelling, systems engineering, and software development paradigms. IEMs are developed for the purpose of integrating knowledge across the various disciplines involved, whereas traditional approaches focus on single systems within the SES, such as hydrology, economics, social dynamics, or climatic drivers. Use of IEMs allows for the consideration of the flow-on effects due to system changes and interaction, and how these may affect long-term SES behaviour. Pathways that are robust - i.e., lead to beneficial or desirable outcomes - under a range of plausible but uncertain conditions can then be identified and assessed. An interconnected network of system models thus makes up an SoS model allowing consideration of higher-order effects. In practice, however, the decisions and approaches taken in developing constituent models may influence integrated system behaviour once coupled. The socio-technical modelling concerns within the SoS/SES modelling context, including the methods to assess and manage model validity, complexity, and uncertainty, with respect to model purpose and intended outcomes are explored through a series of publications. This thesis contributes to the growing body of knowledge through: 1. An expansive overview of the currently available software for model uncertainty and sensitivity analysis, and the techniques they encompass 2. An integrated environmental model for the Lower Campaspe catchment in North-Central Victoria, Australia. The model explores long-term implications of water management decisions and potential policy changes (primarily through an agricultural lens), including conjunctive use of surface and groundwater under a range of uncertain futures. 3. Demonstration of a property-based sensitivity analysis approach to model diagnostics that combines software testing and sensitivity analysis to validate model behaviour. The approach is useful as a first-pass screening tool. Failure to reproduce expected model behaviour indicates issues with the model to be corrected and avoids the necessity of more computationally demanding diagnostics. 4. A pragmatic step-by-step framework for the sensitivity analysis of spatially distributed environmental models 5. Exploration and discussion of the modelling practices, issues and challenges that arise when dealing with the various influences and effects of scale within the interdisciplinary SoS context through a socio-technical lens. The discussion leads to a call for a grander vision for SoS-IEM modelling (and commensurate funding) to better enable interdisciplinary, and integrative, socio-environmental research to occur. 6. A shared reflexive account of two case studies that draws out the considerations and decisions regarding scale to arrive at five shared lessons learnt to foster an effective interdisciplinary modelling process. The key conclusion is the need for researchers involved in SoS modelling of SESs to actively consider and address cross-disciplinary concerns through improved interdisciplinary communication, documentation practices, and explicit consideration of the interplay between defined scales and resulting influence on uncertainty. Integrative consideration of these would then lower or avoid barriers that hamper the development and application of integrated environmental system models

Early Stage Embodied and Operational Analysis for Guiding Sustainable Architectural Design Decisions

Buildings account for a significant portion of global energy consumption and greenhouse gas emissions. Simulating building performance in the early design stage allows architects and engineers to adjust design decisions to reduce embodied carbon and energy consumption. Life-cycle assessment (LCA) is one of the most comprehensive methodologies to evaluate the environmental impact of architectural production and operation. This thesis aims to address the challenges involved in applying LCA to architectural design in the early design stage. By conducting a literature review of the status quo of architectural LCA and identifying the gaps in existing research and tools, this paper continues the research of a novel workflow in Grasshopper that calculates greenhouse gas (GHG) emissions and costs from both embodied and operational phases. The workflow addresses the early-stage uncertainty through random inputs with a Monte Carlo approach and implements surrogate models to accelerate the process for each iteration. The author's contribution to the workflow includes improving its robustness and accuracy by redesigning the simulation model to generate more accurate training data and transitioning to a new machine-learning algorithm. The results of the study provide insights into design decisions that can reduce embodied and operational carbon. A parallel case study was conducted to assess the trade-offs between embodied and operational carbon with regard to construction material selection. In the end, the thesis also proposes possible future research directions.S.M