DecDoc: A Tool for Documenting Design Decisions Collaboratively and Incrementally

Abstract

The outcome and quality of design decisions highly depend on the knowledge reflected during decision-making. Typically, making design decisions is not one singular action.Instead, developers discuss and cooperate during requirements engineering, design and implementation of a system to make and adapt design decisions. This decision-making process is influenced by different decision-making strategies, personal experiences, and biases. In consequence, decision-related knowledge emerges incrementally over time in an incomplete and heterogeneous way. This hinders the documentation of such knowledge in practice. First, most documentation tools capture decision-related knowledge within one particular development activity.However, they do not focus on the collaborative and shared documentation during multiple activities. Second, static documentation templates and formal rules are not suitable for capturing incomplete knowledge, as additional documentation effort is imposed for developers. Thus, text templates are not used or filled with generic contents. As a result, decision-related knowledge remains implicit and is not available to guide future decision-making. To address these issues, we have created the tool DecDoc based on our incremental documentation model. The tool enables developers to capture decision-related knowledge and collaborate on a comprehensive documentation of design decisions with relations to artifacts, such as requirement specifications, design diagrams, and code. This helps to improve the decision-making process for design decisions, as it helps to make explicit and reflect related knowledge during the process. In this paper, we present DecDoc with regard to requirements from the decision-making process.Then, we describe its application on design decisions in example projects. Finally, we discuss our insights from using the tool and highlight open challenges.