Personalized architectural documentation based on stakeholders’ information needs

Abstract

Background: The stakeholders of a software system are, to a greater or lesser extent, concerned about its software architecture, as an essential artifact for capturing the key design decisions of the system. The architecture is normally documented in the Software Architecture Document (SAD), which tends to be a large and complex technical description, and does not always address the information needs of every stakeholder. Individual stakeholders are interested in different, sometimes overlapping, subsets of the SAD and they also require varying levels of detail. As a consequence, stakeholders are affected by an information overload problem, which in practice discourages the usage of the architectural knowledge and diminishes its value for the organization. Methods: This work presents a semi-automated approach to recommend relevant contents of a given SAD to specific stakeholder profiles. Our approach assumes that SADs are hosted in Wikis, which not only favor communication and interactions among stakeholders, but also enable us to apply User Profiling techniques to infer stakeholders' interests with respect to particular documents. Results: We have built a recommendation tool implementing our approach, which was tested in two experiments with Wiki-based SADs. The experiments aimed at assessing the performance reached by our tool when inferring stakeholders' interests. To this end, precision and recall metrics were used. Conclusions: Although preliminary, the results have shown that the recommendations of the tool help to find the architectural documents that best match the stakeholders' interests.

Producing Just Enough Documentation: An Optimization Approach Applied to the Software Architecture Domain

“…As for the integration of user proling techniques in ProSAD, we argue that the component can have a dual purpose, supporting the writers and the readers of the SAD. On the reader's side, a personalization tool could identify potentially-relevant SAD sections for specic stakeholders, alleviating information overload problems [35]. As future work, we would like to study measures for quantifying the internal quality of a SAD, and possibly incorporate it as a third objective in our optimization formulation.…”

“…Second, a limitation of [36] was the assumption that the stakeholders had a xed set of interests on the SAD contents. Thus, we here discuss a model for incorporating variations in the stakeholders' interests based on user proling techniques [35]. Third, in [36] it was necessary to provide certain documentation costs and priorities of stakeholders as input parameters to the optimization model.…”

An optimization‐based tool to support the cost‐effective production of software architecture documentation

“…As future work, we plan to Replicate experiment 2 with a different group of test subjects and on different SADs, so as to obtain more data and check our initial findings. In particular, we believe a larger study with our optimization framework can help us to investigate the correlation between SAD quality (e.g., utility) and stakeholders' satisfaction (e.g., support). Evaluate and compare the performance of NSGA‐II with other state‐of‐the‐art multi‐objective algorithms to solve our optimization problem. Enhance the current prototype of SADHelper and integrate it with development tools (IDEs, CASE tools, or planning tools), so as to foster the adoption of our approach in real software projects. Study measures for quantifying the internal quality of a SAD, and possibly incorporate it as a third objective in our optimization formulation. Apply sensitivity analysis techniques to make our optimization formulation more robust (e.g., to variations in costs, stakeholders' priorities, or satisfaction functions, among others). Customize the SCM on the basis of individual stakeholder interests via user profiling techniques . …”

Task-Specific Architecture Documentation for Developers

“…data on how particular or former users looked for comparable pieces of information is used to identify and select relevant information. Two of the approaches we have analyzed fall into this category: Nicoletti et al developed a r recommendation tool based on DokuWiki [Andr18], which implements a "semi-automated approach to recommend relevant contents of a given SAD to specific stakeholder profiles" [NDST14]. This is achieved with the help of user profiles.…”