Design Decision Documentation: A Literature Overview

Alexeeva, Zoya; Pérez-Palacín, Diego; Mirandola, Raffaela

doi:10.1007/978-3-319-48992-6_6

Cited by 14 publications

(4 citation statements)

References 85 publications

Supporting

Mentioning

Contrasting

Order By: Relevance

“…Moreover, developers still believe that, if they remember what to do, TD annotations are redundant or confusing. Reliance on one's memory can create multiple problems including lack of traceability and documentation of decisions taken (Aranda and Venolia, 2009;Falessi et al, 2013;Alexeeva et al, 2016). Not only this makes the life hard for project newcomers, but, in extreme cases, it can provoke truck factor events (Avelino et al, 2016;Torchiano et al, 2011), making the source code hard to be maintained or project becoming abandoned (Avelino et al, 2019).…”

Section: Implication 2bmentioning

confidence: 99%

Self-admitted technical debt practices: a comparison between industry and open-source

et al. 2021

View full text Add to dashboard Cite

Self-admitted technical debt (SATD) consists of annotations, left by developers as comments in the source code or elsewhere, as a reminder about pieces of software manifesting technical debt (TD), i.e., "not being ready yet". While previous studies have investigated SATD management and its relationship with software quality, there is little understanding of the extent and circumstances to which developers admit TD. This paper reports the results of a study in which we asked developers from industry and opensource about their practices in annotating source code and other artifacts for self-admitting TD. The study consists of two phases. First, we conducted 10 interviews to gather a first understanding of the phenomenon and to prepare a survey questionnaire. Then, we surveyed 52 industrial developers as well as 49 contributors to open-source projects. Results of the study show how the TD annotation practices, as well as the typical content of SATD comments, are very similar between open-source and industry. At the same time, our results highlight how, while open-source code is spread of comments admitting the need for improvements, SATD in industry may be dictated by organizational guidelines but, at the same time, implicitly discouraged by the fear of admitting

show abstract

Section: Implication 2bmentioning

confidence: 99%

Self-admitted technical debt practices: a comparison between industry and open-source

et al. 2021

View full text Add to dashboard Cite

show abstract

“…Capturing decision knowledge has many benefits, eg, it improves decision making through making criteria explicit and prevents knowledge vaporization . However, decision knowledge is often not captured in practice . CSE offers new opportunities to overcome this capture problem since it provides multiple practices and documentation locations in which developers can capture decision knowledge.…”

Section: Foundationsmentioning

confidence: 99%

Continuous software engineering and its support by usage and decision knowledge: An interview study with practitioners

Johanßen

Kleebaum

Paech

et al. 2019

J Software Evolu Process

View full text Add to dashboard Cite

Continuous software engineering (CSE) emerged as a process that is increasingly applied by practitioners. However, different perceptions impede its adoption in industry. Furthermore, opportunities through utilizing usage and decision knowledge remain unexploited. We conducted a semi‐structured interview study with 24 practitioners from 17 companies to study how practitioners apply CSE during software evolution and how usage and decision knowledge can support CSE. Regarding the application of CSE, we identified five perspectives on CSE with tool‐ and methodology‐driven definitions most prevalent. Automated tests, involved users, and shared rulesets are perceived as most relevant for CSE. Practitioners report more positive than negative experiences; however, more than half of their responses were neutral. Practitioners' future plans for CSE focus on enhancement, expansion, and on‐demand adaption. Regarding the integration of usage and decision knowledge into CSE, practitioners perceive accountability and traceability as major benefits, while raising concerns about its feasibility and user groups. As short‐term extensions, practitioners expect improvements regarding automation and role aspects, while long‐term additions to integration and experimentation capabilities are demanded. We conclude that CSE remains partially difficult to capture for practitioners, while their attitude toward integrating usage and decision knowledge into CSE is positive.

show abstract

“…A large body of research work on capturing architectural decisions exists; the state of the art is for instance surveyed by Alexeeva et al [2] and by Capilla et al [4]. Specifically to the context of service orientation and service composition, the SOA Decision Modeling (SOAD) project [17] investigated architectural decisions recurring in SOA design and introduced a seven-step method to identify, make, and capture such decisions.…”

Section: Background and Related Workmentioning

confidence: 99%

The LaTeX template generator: How micro-templates reduce template maintenance effort

Kopp

2023

TUGboat

View full text Add to dashboard Cite

Architectural decision records answer "why" questions about designs and make tacit knowledge explicit. Many architectural decisions are made during development iterations because they have a close connection to the code. It is challenging to come up with task-specific decision capturing practices and supporting tools that are not perceived as time wasters; context switches and media breaks that harm the productivity of coding architects and developers involved in the decision making have to be avoided. To integrate existing architect-centric approaches into the developer toolchain, this paper presents a Markdown-based decision capturing template that we derived from previous work to enhance an existing decision capturing tool for developers. Our early validation results in the context of an open source project suggest that format and tool promise to contribute to an integrated decision capturing practice, with further enhancements being required. Tool and template are available in public GitHub repositories.

show abstract

Design Decision Documentation: A Literature Overview

Cited by 14 publications

References 85 publications

Self-admitted technical debt practices: a comparison between industry and open-source

Self-admitted technical debt practices: a comparison between industry and open-source

Continuous software engineering and its support by usage and decision knowledge: An interview study with practitioners

The LaTeX template generator: How micro-templates reduce template maintenance effort

Contact Info

Product

Resources

About